Trello
STDIOHTTP-SSEMCP server for Trello board management and integration with API features.
MCP server for Trello board management and integration with API features.
A Model Context Protocol (MCP) server that provides tools for interacting with Trello boards. This server enables seamless integration with Trello's API while handling rate limiting, type safety, and error handling automatically.
Comprehensive Checklist Tools are here! 🚀 Now you can fully manage Trello checklists with 5 powerful new tools! Search, create, and track checklist items across your boards. Perfect for managing acceptance criteria, development tasks, and project milestones!
get_checklist_items - Retrieve all items from any checklist by nameadd_checklist_item - Add new items to existing checklistsfind_checklist_items_by_description - Search checklist items by text contentget_acceptance_criteria - Quick access to "Acceptance Criteria" checklistsget_checklist_by_name - Get complete checklist with completion percentagePlus: Modern MCP SDK architecture, enhanced type safety, and comprehensive documentation!
🎊 Major Feature Release: Complete Checklist Management Suite
get_checklist_items(name) - Retrieve all items from a checklist by nameadd_checklist_item(text, checkListName) - Add new items to existing checklistsfind_checklist_items_by_description(description) - Search checklist items by text contentget_acceptance_criteria() - Convenience method for "Acceptance Criteria" checklistsget_checklist_by_name(name) - Get complete checklist with completion percentageregisterTool() and Zod validationCheckList and CheckListItem interfaces for structured checklist dataCHECKLIST_TOOLS.md with examples and best practices🎊 Major Feature Release: Complete Card Data Extraction
get_card tool for comprehensive single card data retrievalincludeMarkdown parameter returns beautifully formatted, human-readable card datapnpx @delorenj/mcp-server-trelloboardId parameter (thanks @blackoutnet!)TRELLO_BOARD_ID environment variable is now optional and serves as default boardlist_boards - List all boards the user has access toset_active_board - Set the active board for future operationslist_workspaces - List all workspaces the user has access toset_active_workspace - Set the active workspace for future operationslist_boards_in_workspace - List all boards in a specific workspaceget_active_board_info - Get information about the currently active boardattach_file_to_card tool to attach any type of file (PDFs, documents, videos, etc.) to cards from URLsattach_image_to_card for backward compatibilityattach_image_to_card tool to attach images to cards from URLs.env.env.template for easier setupmove_card tool to move cards between listsThe easiest way to use the Trello MCP server is with pnpx, which doesn't require a global install:
{ "mcpServers": { "trello": { "command": "pnpx", "args": ["@delorenj/mcp-server-trello"], "env": { "TRELLO_API_KEY": "your-api-key", "TRELLO_TOKEN": "your-token" } } } }
Or if you're using mise:
{ "mcpServers": { "trello": { "command": "mise", "args": ["x", "--", "pnpx", "@delorenj/mcp-server-trello"], "env": { "TRELLO_API_KEY": "your-api-key", "TRELLO_TOKEN": "your-token" } } } }
To connect a Trello workspace, you'll need to manually retrieve a TRELLO_TOKEN once per workspace. After setting up your Trello Power-Up, visit the following URL:
https://trello.com/1/authorize?expiration=never&name=YOUR_APP_NAME&scope=read,write&response_type=token&key=YOUR_API_KEY
Replace:
YOUR_APP_NAME with a name for your application (e.g., "My Trello Integration"). This name is shown to the user on the Trello authorization screen.YOUR_API_KEY with the API key for your Trello Power-UpThis will generate the token required for integration.
[!NOTE] The
expiration=neverparameter creates a token that does not expire. For enhanced security, consider usingexpiration=30daysand renewing the token periodically if your setup allows for it.
The simplest way to get pnpm (and thus pnpx) is through mise:
# Install mise (if you don't have it) curl https://mise.run | sh # Install pnpm with mise mise install pnpm
If you prefer using npm directly:
npm install -g @delorenj/mcp-server-trello
Then use npx mcp-server-trello as the command in your MCP configuration.
To install Trello Server for Claude Desktop automatically via Smithery:
npx -y @smithery/cli install @delorenj/mcp-server-trello --client claude
For containerized environments:
git clone https://github.com/delorenj/mcp-server-trello cd mcp-server-trello
cp .env.template .env
docker compose up --build
The server can be configured using environment variables. Create a .env file in the root directory with the following variables:
# Required: Your Trello API credentials TRELLO_API_KEY=your-api-key TRELLO_TOKEN=your-token # Optional (Deprecated): Default board ID (can be changed later using set_active_board) TRELLO_BOARD_ID=your-board-id # Optional: Initial workspace ID (can be changed later using set_active_workspace) TRELLO_WORKSPACE_ID=your-workspace-id
You can get these values from:
list_workspaces toolStarting with version 0.3.0, the MCP server supports multiple ways to work with boards:
Multi-board support: All methods now accept an optional boardId parameter
TRELLO_BOARD_ID and provide boardId in each API callTRELLO_BOARD_ID as default and optionally override with boardId parameterDynamic board selection: Use workspace management tools
TRELLO_BOARD_ID in your .env file is used as the initial/default board IDset_active_board tool~/.trello-mcp/config.json)set_active_workspaceThis allows you to work with multiple boards and workspaces without restarting the server.
{ name: 'list_boards', arguments: {} }
{ name: 'set_active_board', arguments: { boardId: "abc123" // ID from list_boards response } }
{ name: 'list_workspaces', arguments: {} }
{ name: 'set_active_workspace', arguments: { workspaceId: "xyz789" // ID from list_workspaces response } }
{ name: 'get_active_board_info', arguments: {} }
When working with dates in the Trello MCP server, please note the different format requirements:
dueDate): Accepts full ISO 8601 format with time (e.g., 2023-12-31T12:00:00Z)start): Accepts date only in YYYY-MM-DD format (e.g., 2025-08-05)This distinction follows Trello's API conventions where start dates are day-based markers while due dates can include specific times.
Get all items from a checklist by name.
{ name: 'get_checklist_items', arguments: { name: string, // Name of the checklist to retrieve items from boardId?: string // Optional: ID of the board (uses default if not provided) } }
Add a new item to an existing checklist.
{ name: 'add_checklist_item', arguments: { text: string, // Text content of the checklist item checkListName: string, // Name of the checklist to add the item to boardId?: string // Optional: ID of the board (uses default if not provided) } }
Search for checklist items containing specific text.
{ name: 'find_checklist_items_by_description', arguments: { description: string, // Text to search for in checklist item descriptions boardId?: string // Optional: ID of the board (uses default if not provided) } }
Get all items from the "Acceptance Criteria" checklist.
{ name: 'get_acceptance_criteria', arguments: { boardId?: string // Optional: ID of the board (uses default if not provided) } }
Get a complete checklist with all items and completion percentage.
{ name: 'get_checklist_by_name', arguments: { name: string, // Name of the checklist to retrieve boardId?: string // Optional: ID of the board (uses default if not provided) } }
Returns: CheckList object with:
id: Checklist identifiername: Checklist nameitems: Array of CheckListItem objectspercentComplete: Completion percentage (0-100)Get comprehensive details of a specific Trello card with human-level parity.
{ name: 'get_card', arguments: { cardId: string, // ID of the Trello card (short ID like 'FdhbArbK' or full ID) includeMarkdown?: boolean // Return formatted markdown instead of JSON (default: false) } }
Returns: Complete card data including:
Fetch all cards from a specific list.
{ name: 'get_cards_by_list_id', arguments: { boardId?: string, // Optional: ID of the board (uses default if not provided) listId: string // ID of the Trello list } }
Retrieve all lists from a board.
{ name: 'get_lists', arguments: { boardId?: string // Optional: ID of the board (uses default if not provided) } }
Fetch recent activity on a board.
{ name: 'get_recent_activity', arguments: { boardId?: string, // Optional: ID of the board (uses default if not provided) limit?: number // Optional: Number of activities to fetch (default: 10) } }
Add a new card to a specified list.
{ name: 'add_card_to_list', arguments: { boardId?: string, // Optional: ID of the board (uses default if not provided) listId: string, // ID of the list to add the card to name: string, // Name of the card description?: string, // Optional: Description of the card dueDate?: string, // Optional: Due date (ISO 8601 format with time) start?: string, // Optional: Start date (YYYY-MM-DD format, date only) labels?: string[] // Optional: Array of label IDs } }
Update an existing card's details.
{ name: 'update_card_details', arguments: { boardId?: string, // Optional: ID of the board (uses default if not provided) cardId: string, // ID of the card to update name?: string, // Optional: New name for the card description?: string, // Optional: New description dueDate?: string, // Optional: New due date (ISO 8601 format with time) start?: string, // Optional: New start date (YYYY-MM-DD format, date only) dueComplete?: boolean,// Optional: Mark the due date as complete (true) or incomplete (false) labels?: string[] // Optional: New array of label IDs } }
Send a card to the archive.
{ name: 'archive_card', arguments: { boardId?: string, // Optional: ID of the board (uses default if not provided) cardId: string // ID of the card to archive } }
Add a new list to a board.
{ name: 'add_list_to_board', arguments: { boardId?: string, // Optional: ID of the board (uses default if not provided) name: string // Name of the new list } }
Send a list to the archive.
{ name: 'archive_list', arguments: { boardId?: string, // Optional: ID of the board (uses default if not provided) listId: string // ID of the list to archive } }
Fetch all cards assigned to the current user.
{ name: 'get_my_cards', arguments: {} }
Move a card to a different list.
{ name: 'move_card', arguments: { boardId?: string, // Optional: ID of the target board (uses default if not provided) cardId: string, // ID of the card to move listId: string // ID of the target list } }
Attach an image to a card directly from a URL.
{ name: 'attach_image_to_card', arguments: { boardId?: string, // Optional: ID of the board (uses default if not provided) cardId: string, // ID of the card to attach the image to imageUrl: string, // URL of the image to attach name?: string // Optional: Name for the attachment (defaults to "Image Attachment") } }
Attach any type of file to a card from a URL or a local file path (e.g., file:///path/to/your/file.pdf).
{ name: 'attach_file_to_card', arguments: { boardId?: string, // Optional: ID of the board (uses default if not provided) cardId: string, // ID of the card to attach the file to fileUrl: string, // URL or local file path (using the file:// protocol) of the file to attach name?: string, // Optional: Name for the attachment (defaults to the file name for local files) mimeType?: string // Optional: MIME type (e.g., "application/pdf", "text/plain", "video/mp4") } } ### list_boards List all boards the user has access to. ```typescript { name: 'list_boards', arguments: {} }
Set the active board for future operations.
{ name: 'set_active_board', arguments: { boardId: string // ID of the board to set as active } }
List all workspaces the user has access to.
{ name: 'list_workspaces', arguments: {} }
Set the active workspace for future operations.
{ name: 'set_active_workspace', arguments: { workspaceId: string // ID of the workspace to set as active } }
List all boards in a specific workspace.
{ name: 'list_boards_in_workspace', arguments: { workspaceId: string // ID of the workspace to list boards from } }
Get information about the currently active board.
{ name: 'get_active_board_info', arguments: {} }
The Trello MCP server pairs beautifully with @flowluap/ideogram-mcp-server for AI-powered visual content creation. Generate images with Ideogram and attach them directly to your Trello cards!
// Using ideogram-mcp-server { name: 'generate_image', arguments: { prompt: "A futuristic dashboard design with neon accents", aspect_ratio: "16:9" } } // Returns: { image_url: "https://..." }
// Using trello-mcp-server { name: 'attach_image_to_card', arguments: { cardId: "your-card-id", imageUrl: "https://...", // URL from Ideogram name: "Dashboard Mockup v1" } }
Add both servers to your Claude Desktop configuration:
{ "mcpServers": { "trello": { "command": "pnpx", "args": ["@delorenj/mcp-server-trello"], "env": { "TRELLO_API_KEY": "your-trello-api-key", "TRELLO_TOKEN": "your-trello-token" } }, "ideogram": { "command": "pnpx", "args": ["@flowluap/ideogram-mcp-server"], "env": { "IDEOGRAM_API_KEY": "your-ideogram-api-key" } } } }
Now you can seamlessly create visual content and organize it in Trello, all within Claude!
The server implements a token bucket algorithm for rate limiting to comply with Trello's API limits:
Rate limiting is handled automatically, and requests will be queued if limits are reached.
The server provides detailed error messages for various scenarios:
git clone https://github.com/delorenj/mcp-server-trello cd mcp-server-trello
npm install
npm run build
The evals package loads an mcp client that then runs the index.ts file, so there is no need to rebuild between tests. You can load environment variables by prefixing the npx command. Full documentation can be found here.
OPENAI_API_KEY=your-key npx mcp-eval src/evals/evals.ts src/index.ts
Contributions are welcome!
This project is licensed under the MIT License - see the LICENSE file for details.