# MCP Server Trello [![Verified on MseeP](https://mseep.ai/badge.svg)](https://mseep.ai/app/27359682-7632-4ba7-981d-7dfecadf1c4b) [![MCP Registry](https://img.shields.io/badge/MCP-Registry-blue)](https://registry.modelcontextprotocol.io/servers/io.github.delorenj/mcp-server-trello) [![npm version](https://badge.fury.io/js/%40delorenj%2Fmcp-server-trello.svg)](https://badge.fury.io/js/%40delorenj%2Fmcp-server-trello)

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. ## 🎉 New in v1.5.0: Now Powered by Bun! ⚡ **This project is now powered by Bun!** 🚀 We've migrated the entire project to the Bun runtime, resulting in a 2.8-4.4x performance boost. All existing `npx`, `pnpx`, and `npm` commands will **continue to work perfectly**. ### ✨ New in This Release: - 🚀 **Performance Boost**: Enjoy a faster, more responsive server. - BUN **Bun-Powered**: The project now runs on the lightning-fast Bun runtime. - 📖 **Comprehensive Examples**: A new `examples` directory with detailed implementations in JavaScript, Python, and TypeScript. **Plus:** Modern MCP SDK architecture, enhanced type safety, and comprehensive documentation! ## Changelog For a detailed list of changes, please refer to the [CHANGELOG.md](CHANGELOG.md) file. ## Features - **Full Trello Board Integration**: Interact with cards, lists, and board activities - **🆕 Complete Card Data Extraction**: Fetch all card details including checklists, attachments, labels, members, and comments - **💬 Comment Management**: Add, update, delete, and retrieve comments on cards - **File Attachments**: Attach any type of file to cards (PDFs, documents, videos, images, etc.) from URLs - **Built-in Rate Limiting**: Respects Trello's API limits (300 requests/10s per API key, 100 requests/10s per token) - **Type-Safe Implementation**: Written in TypeScript with comprehensive type definitions - **Input Validation**: Robust validation for all API inputs - **Error Handling**: Graceful error handling with informative messages - **Dynamic Board Selection**: Switch between boards and workspaces without restarting - **Markdown Formatting**: Export card data in human-readable markdown format ## Installation ### 🚀 Install from MCP Registry (Recommended) The MCP Server Trello is now available in the official MCP Registry\! MCP clients can automatically discover and install this server. For clients that support the MCP Registry: 1. Search for "mcp-server-trello" or "io.github.delorenj/mcp-server-trello" 2. Install directly from the registry 3. Configure with your Trello credentials ### 🚀 Quick Start with Bun (Fastest) If you have [Bun](https://bun.sh) installed, using `bunx` is the fastest way to run the server: ```json { "mcpServers": { "trello": { "command": "bunx", "args": ["@delorenj/mcp-server-trello"], "env": { "TRELLO_API_KEY": "your-api-key", "TRELLO_TOKEN": "your-token" } } } } ``` ### Quick Start with npx / pnpx / bunx You can still use `npx` or `pnpx`. This doesn't require a global install and will work just fine, though `bunx` (above) is faster. ```json { "mcpServers": { "trello": { "command": "bunx", "args": ["@delorenj/mcp-server-trello"], "env": { "TRELLO_API_KEY": "your-api-key", "TRELLO_TOKEN": "your-token" } } } } ``` Or if you're using mise, you can explicitly execute `bunx` with `mise exec`: ```json { "mcpServers": { "trello": { "command": "mise", "args": ["x", "--", "bunx", "@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-Up This will generate the token required for integration. > [\!NOTE] > The `expiration=never` parameter creates a token that does not expire. For enhanced security, consider using `expiration=30days` and renewing the token periodically if your setup allows for it. #### Don't have Bun? The simplest way to get `bun` (and thus `bunx`) is through [mise](https://mise.jdx.dev/): ```bash # Install mise (if you don't have it) curl https://mise.run | sh # Install bun and make the @latest version your system default mise use bun@latest -g # Or just run `mise install` from the project directory to install Bun locally cd /path/to/mcp-server-trello mise install ``` ### Installing via npm If you prefer using `npm` directly: ```bash npm install -g @delorenj/mcp-server-trello ``` *(A fast alternative is `bun add -g @delorenj/mcp-server-trello`)* Then use `npx mcp-server-trello` as the command in your MCP configuration. ### Installing via Smithery To install Trello Server for Claude Desktop automatically via [Smithery](https://smithery.ai/server/@delorenj/mcp-server-trello): ```bash # Using bunx (recommended) bunx -y @smithery/cli install @delorenj/mcp-server-trello --client claude # Using npx npx -y @smithery/cli install @delorenj/mcp-server-trello --client claude ``` ### Docker Installation For containerized environments: 1. Clone the repository: ```bash git clone https://github.com/delorenj/mcp-server-trello cd mcp-server-trello ``` 2. Copy the environment template and fill in your Trello credentials: ```bash cp .env.template .env ``` 3. Build and run with Docker Compose: ```bash docker compose up --build ``` ## Configuration ### Environment Variables The server can be configured using environment variables. Create a `.env` file in the root directory with the following variables: ```env # 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: - API Key: [https://trello.com/app-key](https://trello.com/app-key) - Token: Generate using your API key - Board ID (optional, deprecated): Found in the board URL (e.g., [suspicious link removed]) - Workspace ID: Found in workspace settings or using `list_workspaces` tool ### Board and Workspace Management Starting with version 0.3.0, the MCP server supports multiple ways to work with boards: 1. **Multi-board support**: All methods now accept an optional `boardId` parameter - Omit `TRELLO_BOARD_ID` and provide `boardId` in each API call - Set `TRELLO_BOARD_ID` as default and optionally override with `boardId` parameter 2. **Dynamic board selection**: Use workspace management tools - The `TRELLO_BOARD_ID` in your `.env` file is used as the initial/default board ID - You can change the active board at any time using the `set_active_board` tool - The selected board persists between server restarts (stored in `~/.trello-mcp/config.json`) - Similarly, you can set and persist an active workspace using `set_active_workspace` This allows you to work with multiple boards and workspaces without restarting the server. #### Example Workflow 1. Start by listing available boards: ```typescript { name: 'list_boards', arguments: {} } ``` 2. Set your active board: ```typescript { name: 'set_active_board', arguments: { boardId: "abc123" // ID from list_boards response } } ``` 3. List workspaces if needed: ```typescript { name: 'list_workspaces', arguments: {} } ``` 4. Set active workspace if needed: ```typescript { name: 'set_active_workspace', arguments: { workspaceId: "xyz789" // ID from list_workspaces response } } ``` 5. Check current active board info: ```typescript { name: 'get_active_board_info', arguments: {} } ``` ## Date Format Guidelines When working with dates in the Trello MCP server, please note the different format requirements: - **Due Date (`dueDate`)**: Accepts full ISO 8601 format with time (e.g., `2023-12-31T12:00:00Z`) - **Start Date (`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. ## Available Tools ### Checklist Management Tools 🆕 #### get\_checklist\_items Get all items from a checklist by name. ```typescript { 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\_checklist\_item Add a new item to an existing checklist. ```typescript { 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) } } ``` #### find\_checklist\_items\_by\_description Search