mcp-server-trello
A Model Context Protocol (MCP) server that provides tools for interacting with Trello boards.
Safety scan
A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.
Badge for your README
Markdown
[](/listings/delorenj--mcp-server-trello)HTML
<a href="/listings/delorenj--mcp-server-trello"><img src="/api/listings/delorenj--mcp-server-trello/badge.svg" alt="findsafeskills safety rating" /></a>Install
Install instructions from the README
As written by the repo's author. findsafeskills has not verified these steps.
The server is published on npm as `@delorenj/mcp-server-trello`. Add it to your MCP client and you're done — no clone, no build.
Quickstart (Claude Desktop, Cursor, and other MCP clients)
Add the server to your client's MCP configuration:
{
"mcpServers": {
"trello": {
"command": "bunx",
"args": ["@delorenj/mcp-server-trello"],
"env": {
"TRELLO_API_KEY": "your-trello-api-key",
"TRELLO_TOKEN": "your-trello-token"
}
}
}
}`bunx` starts fastest, but `npx` works identically. Get your API key at [trello.com/app-key](https://trello.com/app-key) and generate a token from the same page.
Claude Code
Register the server with the CLI:
claude mcp add trello \ --env TRELLO_API_KEY=your-trello-api-key \ --env TRELLO_TOKEN=your-trello-token \ -- bunx @delorenj/mcp-server-trello
MCP Registry
The server is listed on the [official MCP Registry](https://registry.modelcontextprotocol.io/servers/io.github.delorenj/mcp-server-trello) as `io.github.delorenj/mcp-server-trello`, so registry-aware clients can discover and install it directly.
Agent skill package (optional)
This repository also ships a **BMAD-compatible skill package** for the Trello MCP server. Install the `skill/` directory through your agent's skill management workflow, or place it in the agent's skills directory.
When an agent activates the skill, it follows `skill/SKILL.md`. On first use, the agent runs the bundled installer:
bash skill/scripts/install.sh
The installer builds the MCP server from `skill/assets/source/` when Bun is available. If Bun is unavailable, it falls back to the published Smithery install path for `@delorenj/mcp-server-trello` and creates the same local `build/index.js` command path used by the skill activation check.
What was scanned
The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.
README.md · README · 981 lines
View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)
- # MCP Server Trello
- [](https://mseep.ai/app/27359682-7632-4ba7-981d-7dfecadf1c4b)
- [](https://registry.modelcontextprotocol.io/servers/io.github.delorenj/mcp-server-trello)
- [](https://badge.fury.io/js/%40delorenj%2Fmcp-server-trello)
- <a href="https://glama.ai/mcp/servers/klqkamy7wt"><img width="380" height="200" src="https://glama.ai/mcp/servers/klqkamy7wt/badge" alt="Server Trello MCP server" /></a>
- A Model Context Protocol (MCP) server that gives AI agents full access to your Trello boards — cards, lists, checklists, attachments, comments, custom fields, and workspaces — with built-in rate limiting, type safety, and workflow-level tools you won't find in a plain API wrapper, like acceptance-criteria extraction and checklist dependency queries. 57 tools, one `npx` install, powered by Bun.
- ## Highlights
- - **Acceptance criteria, natively**: `get_acceptance_criteria` pulls a card's AC checklist straight into your agent's context — no competitor offers it.
- - **Watch anything**: `watch_card` and `watch_list` route card and list activity into your Trello notifications.
- - **Full list management**: create, update, reorder (`update_list_position`), and archive lists.
- - **Board and workspace switching on the fly**: no restarts, no config edits.
- - **Rate limiting handled for you**: respects Trello's API limits automatically (300 req/10s per key, 100 req/10s per token).
- - **Bun-powered**: fast startup and a 2.8-4.4x performance boost over the old Node build. `npx` and `npm` work too.
- ## Changelog
- For a detailed list of changes, see [CHANGELOG.md](CHANGELOG.md).
- ## Features
- - **Full Trello Board Integration**: Interact with cards, lists, and board activities
- - **Acceptance Criteria Extraction**: Pull a card's acceptance criteria checklist directly into agent context
- - **Checklist Intelligence**: Query checklist items by name or description, track completion, manage items
- - **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
- - **Activity Subscriptions**: Watch cards and lists so their activity surfaces in Trello notifications
- - **List Management**: Create, update, reorder, and archive lists
- - **File Attachments**: Attach any type of file to cards (PDFs, documents, videos, images, etc.) from URLs
- - **Custom Fields**: Read board custom field definitions and update card values
- - **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
- The server is published on npm as `@delorenj/mcp-server-trello`. Add it to your MCP client and you're done — no clone, no build.
- ### Quickstart (Claude Desktop, Cursor, and other MCP clients)
- Add the server to your client's MCP configuration:
- ```json
- {
- "mcpServers": {
- "trello": {
- "command": "bunx",
- "args": ["@delorenj/mcp-server-trello"],
- "env": {
- "TRELLO_API_KEY": "your-trello-api-key",
- "TRELLO_TOKEN": "your-trello-token"
- }
- }
- }
- }
- ```
- `bunx` starts fastest, but `npx` works identically. Get your API key at [trello.com/app-key](https://trello.com/app-key) and generate a token from the same page.
- ### Claude Code
- Register the server with the CLI:
- ```bash
- claude mcp add trello \
- --env TRELLO_API_KEY=your-trello-api-key \
- --env TRELLO_TOKEN=your-trello-token \
- -- bunx @delorenj/mcp-server-trello
- ```
- ### MCP Registry
- The server is listed on the [official MCP Registry](https://registry.modelcontextprotocol.io/servers/io.github.delorenj/mcp-server-trello) as `io.github.delorenj/mcp-server-trello`, so registry-aware clients can discover and install it directly.
- ### Agent skill package (optional)
- This repository also ships a **BMAD-compatible skill package** for the
- Trello MCP server. Install the `skill/` directory through your agent's skill
- management workflow, or place it in the agent's skills directory.
- When an agent activates the skill, it follows `skill/SKILL.md`. On first use,
- the agent runs the bundled installer:
- ```bash
- bash skill/scripts/install.sh
- ```
- The installer builds the MCP server from `skill/assets/source/` when Bun is
- available. If Bun is unavailable, it falls back to the published Smithery
- install path for `@delorenj/mcp-server-trello` and creates the same local
- `build/index.js` command path used by the skill activation check.
- ## Skill package structure
- The skill is the agent-facing entry point for this repository.
- - `skill/SKILL.md`: Activation, routing, and agent workflow rules.
- - `skill/scripts/install.sh`: First-run installer for the bundled server.
- - `skill/references/trello-mcp/`: Focused references for setup, tools,
- workflows, and gotchas.
- - `skill/assets/source/`: Bundled MCP server source used for local builds.
- For AI agents, start with `skill/SKILL.md` rather than this README. The README
- is the human-facing overview; the skill references are the operational surface
- for tool selection and Trello workflow rules.
- Maintainers can refresh the bundled source before packaging with:
- ```bash
- mise run package
- ```
- ## 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
- # Optional: HTTPS proxy URL (for corporate proxies or restricted networks)
- https_proxy=http://your-proxy:8080
- # Optional: Restrict access to specific workspaces (comma-separated IDs)
- # If set, only the listed workspaces will be accessible via MCP tools
- TRELLO_ALLOWED_WORKSPACES=workspace-id-1,workspace-id-2
- ```
- > **Proxy Support:** If you're behind a corporate proxy or in an environment that routes traffic through a proxy, set the `https_proxy` or `HTTPS_PROXY` environment variable. The server will automatically route all Trello API requests through the specified proxy.
- 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., `https://trello.com/b/abc123/example-board`)
- - 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.
- ### Workspace Access Restriction
- You can optionally restrict MCP access to specific workspaces using the `TRELLO_ALLOWED_WORKSPACES` environment variable. This is useful for:
- - **Security**: Limiting AI agent access to only approved workspaces
- - **Multi-tenant setups**: Ensuring agents only access relevant workspaces
- - **Testing**: Isolating test environments from production data
- When `TRELLO_ALLOWED_WORKSPACES` is set:
- - `list_workspaces` only returns workspaces in the allowed list
- - `list_boards` only returns boards from allowed workspaces
- - `set_active_workspace` rejects workspaces not in the allowed list
- - `list_boards_in_workspace` rejects non-allowed workspace IDs
- - `create_board` rejects creation in non-allowed workspaces
- Example configuration:
- ```bash
- # Only allow access to two specific workspaces
- TRELLO_ALLOWED_WORKSPACES=697c549ce04dc460af133a75,5f8a3b2c1d4e5f6a7b8c9d0e
- ```
- If `TRELLO_ALLOWED_WORKSPACES` is not set or empty, all workspaces the token has access to will be available (default behaviour).
- #### Example Workflow
- 1. Start by listing available boards:
- <!-- end list -->
- ```typescript
- {
- name: 'list_boards',
- arguments: {}
- }
- ```
- 2. Set your active board:
- <!-- end list -->
- ```typescript
- {
- name: 'set_active_board',
- arguments: {
- boardId: "abc123" // ID from list_boards response
- }
- }
- ```
- 3. List workspaces if needed:
- <!-- end list -->
- ```typescript
- {
- name: 'list_workspaces',
- arguments: {}
- }
- ```
- 4. Set active workspace if needed:
- <!-- end list -->
- ```typescript
- {
- name: 'set_active_workspace',
- arguments: {
- workspaceId: "xyz789" // ID from list_workspaces response
- }
- }
- ```
- 5. Check current active board info:
- <!-- end list -->
- ```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 for checklist items containing specific text.
- ```typescript
- {
- 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\_acceptance\_criteria
- Get a card's (or board's) acceptance criteria, tolerating the common checklist headings teams actually use. A checklist matches if its name equals `Acceptance Criteria`, `AC`, `DoD`, or `Definition of Done` — compared case-insensitively and whitespace-trimmed. The first alias in that order with any match wins.
- ```typescript
- {
- name: 'get_acceptance_criteria',
- arguments: {
- cardId?: string, // Optional: ID of the card to scope the search to (recommended to avoid ambiguity)
- boardId?: string // Optional: ID of the board (uses default if not provided)
- }
- }
- ```
- On a match, returns:
- ```typescript
- {
- found: true,
- items: CheckListItem[], // All items of the matching checklist(s), in Trello's order
- unmet: CheckListItem[], // The incomplete subset of items
- percentComplete: number, // Rounded percentage complete; 0 when there are no items
- matchedChecklistName: string // The checklist name as written on the board, original casing
- }
- ```
- When nothing matches, the tool says so explicitly instead of returning an empty list — so "this card has no acceptance criteria" is never confused with "the checklist is named something else":
- ```typescript
- {
- found: false,
- reason: string, // Human-readable explanation naming the aliases that were tried
- availableChecklists: string[] // Names of the checklists that do exist in the searched scope
- }
- ```
- A checklist that matches but has no items returns `found: true` with `items: []`, which is distinct from the not-found response above.
- #### get\_checklist\_by\_name
- Get a complete checklist with all items and completion percentage.
- ```typescript
- {
- 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 identifier
- - `name`: Checklist name
- - `items`: Array of `CheckListItem` objects
- - `percentComplete`: Completion percentage (0-100)
- #### update\_checklist\_item
- Update an existing checklist item.
- ```typescript
- {
- name: 'update_checklist_item',
- arguments: {
- cardId: string, // ID of the card containing the checklist item
- checkItemId: string, // ID of the checklist item to update
- name?: string, // Optional: new checklist item text
- state?: 'complete' | 'incomplete', // Optional: new checklist item state
- pos?: number | 'top' | 'bottom', // Optional: new checklist item position
- due?: string | null, // Optional: ISO 8601 due date, or null to clear it
- dueReminder?: number | null, // Optional: reminder offset in minutes, or null to clear it
- idMember?: string | null // Optional: member ID to assign, or null to clear it
- }
- }
- ```
- #### delete\_checklist\_item
- Delete an existing checklist item.
- ```typescript
- {
- name: 'delete_checklist_item',
- arguments: {
- cardId: string, // ID of the card containing the checklist item
- checkItemId: string // ID of the checklist item to delete
- }
- }
- ```
- ### get\_card 🆕
- Get comprehensive details of a specific Trello card with human-level parity.
- ```typescript
- {
- 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:
- - ✅ Checklists with item states and assignments
- - 📎 Attachments with previews and metadata
- - 🏷️ Labels with names and colors
- - 👥 Assigned members
- - 💬 Comments and activity
- - 📊 Statistics (badges)
- - 🎨 Cover images
- - 📍 Board and list context
- ### get\_cards\_by\_list\_id
- Fetch all cards from a specific list.
- ```typescript
- {
- 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
- }
- }
- ```
- ### get\_lists
- Retrieve all lists from a board.
- ```typescript
- {
- name: 'get_lists',
- arguments: {
- boardId?: string // Optional: ID of the board (uses default if not provided)
- }
- }
- ```
- ### get\_recent\_activity
- Fetch recent activity on a board.
- ```typescript
- {
- 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\_card\_to\_list
- Add a new card to a specified list.
- ```typescript
- {
- 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
- mbs; 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\_card\_details
- Update an existing card's details.
- ```typescript
- {
- 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
- }
- }
- ```
- ### archive\_card
- Send a card to the archive.
- ```typescript
- {
- 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\_list\_to\_board
- Add a new list to a board.
- ```typescript
- {
- 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
- }
- }
- ```
- ### archive\_list
- Send a list to the archive.
- ```typescript
- {
- name: 'archive_list',
- arguments: {
- boardId?: string, // Optional: ID of the board (uses default if not provided)
- listId: string // ID of the list to archive
- }
- }
- ```
- ### update\_list
- Update a list's name, archive state, subscription state, or board. Use `update_list_position` to reorder lists within a board.
- ```typescript
- {
- name: 'update_list',
- arguments: {
- listId: string, // ID of the list to update
- name?: string, // Optional: New name for the list
- closed?: boolean, // Optional: Whether to close (archive) the list
- subscribed?: boolean, // Optional: Whether to subscribe to the list
- idBoard?: string // Optional: ID of a board to move the list to
- }
- }
- ```
- ### update\_list\_position
- Update the position of a list on the board. Trello uses fractional indexing: each list has a float position, and to place a list between two others, use the average of their positions (e.g., between pos 1024 and 2048, use 1536). Use `"top"`/`"bottom"` shortcuts to move to the edges.
- ```typescript
- {
- name: 'update_list_position',
- arguments: {
- listId: string, // ID of the list to reposition
- position: string // "top", "bottom", or a positive numeric string (e.g. "1536")
- }
- }
- ```
- ### get\_my\_cards
- Fetch all cards assigned to the current user.
- ```typescript
- {
- name: 'get_my_cards',
- arguments: {}
- }
- ```
- ### move\_card
- Move a card to a different list.
- ```typescript
- {
- name: 'move_card',
- arguments: {
- boardId?: string, // Optional: ID of the target board (uses default if not provided)
- s; cardId: string, // ID of the card to move
- listId: string // ID of the target list
- }
- }
- ```
- ### attach\_image\_to\_card
- Attach an image to a card directly from a URL.
- ```typescript
- {
- 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\_file\_to\_card
- Attach any type of file to a card from a URL or a local file path (e.g., `file:///path/to/your/file.pdf`).
- ```typescript
- {
- name: 'attach_file_to_card',
- arguments: {
- boardId?: string, // Optional: ID of the board (uses default if not provided)
- cardId: string,s; // 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")
- }
- }
- ```
- ### download\_attachment
- Download an attachment from a card by ID. Attachment IDs are available in the `attachments` array returned by `get_card`.
- ```typescript
- {
- name: 'download_attachment',
- arguments: {
- cardId: string, // ID of the card containing the attachment
- attachmentId: string // ID of the attachment to download
- }
- }
- ```
- **Returns:** For image attachments (`image/*`), returns the image as inline viewable data. For all other file types, returns a JSON object with:
- - `fileName`: Original filename
- - `mimeType`: MIME type of the file
- - `data`: Base64-encoded file contents
- ### Comment Management Tools
- #### add\_comment
- Add a comment to a Trello card.
- ```typescript
- {
- name: 'add_comment',
- arguments: {
- cardId: string, // ID of the card to comment on
- text: string // The text of the comment to add
- }
- }
- ```
- #### update\_comment
- Update an existing comment on a card.
- ```typescript
- {
- name: 'update_comment',
- arguments: {
- commentId: string, // ID of the comment to change
- text: string // The new text of the comment
- }
- }
- ```
- #### delete\_comment
- Delete a comment from a card.
- ```typescript
- {
- name: 'delete_comment',
- arguments: {
- commentId: string // ID of the comment to delete
- }
- }
- ```
- #### get\_card\_comments
- Retrieve all comments from a specific card without fetching all card data.
- ```typescript
- {
- name: 'get_card_comments',
- arguments: {
- cardId: string, // ID of the card to get comments from
- limit?: number // Optional: Maximum number of comments to retrieve (default: 100)
- }
- }
- ```
- ### list\_boards
- List all boards the user has access to.
- ```typescript
- {
- name: 'list_boards',
- arguments: {}
- }
- ```
- ### set\_active\_board
- Set the active board for future operations.
- ```typescript
- {
- name: 'set_active_board',
- arguments: {
- boardId: string // ID of the board to set as active
- }
- }
- ```
- ### list\_workspaces
- List all workspaces the user has access to.
- ```typescript
- {
- s; name: 'list_workspaces',
- arguments: {}
- }
- ```
- ### set\_active\_workspace
- Set the active workspace for future operations.
- ```typescript
- {
- name: 'set_active_workspace',
- arguments: {
- workspaceId: string // ID of the workspace to set as active
- }
- }
- ```
- ### list\_boards\_in\_workspace
- List all boards in a specific workspace.
- ```typescript
- {
- name: 'list_boards_in_workspace',
- arguments: {
- workspaceId: string // ID of the workspace to list boards from
- }
- }
- ```
- ### get\_active\_board\_info
- Get information about the currently active board.
- ```typescript
- {
- s; name: 'get_active_board_info',
- arguments: {}
- }
- ```
- ### Custom Field Management Tools
- > **Note:** Custom fields require Trello Standard plan or higher.
- #### get\_board\_custom\_fields
- Get all custom field definitions on a board. For dropdown/list fields, also returns the available options with their IDs.
- ```typescript
- {
- name: 'get_board_custom_fields',
- arguments: {
- boardId?: string // Optional: ID of the board (uses default if not provided)
- }
- }
- ```
- **Returns:** Array of custom field definitions including:
- - Field ID, name, type (`text`, `number`, `checkbox`, `date`, `list`)
- - For `list` type fields: available options with IDs (use these IDs when setting values)
- #### update\_card\_custom\_field
- Set or clear a custom field value on a card.
- ```typescript
- {
- name: 'update_card_custom_field',
- arguments: {
- cardId: string, // ID of the card to update
- customFieldId: string,// ID of the custom field definition
- type: string, // Field type: 'text' | 'number' | 'checkbox' | 'date' | 'list' | 'clear'
- value?: string // The value to set (not needed when type is 'clear')
- }
- }
- ```
- **Value format by type:**
- - `text`: any string
- - `number`: numeric string (e.g. `"42.5"`)
- - `checkbox`: `"true"` or `"false"`
- - `date`: ISO 8601 string (e.g. `"2025-12-31T00:00:00.000Z"`)
- - `list`: option ID from `get_board_custom_fields`
- - `clear`: omit value to remove the field value
- ## Integration Examples
- ### 🎨 Pairing with Ideogram MCP Server
- The Trello MCP server pairs beautifully with [@flowluap/ideogram-mcp-server](https://github.com/flowluap/ideogram-mcp-server) for AI-powered visual content creation. Generate images with Ideogram and attach them directly to your Trello cards\!
- #### Example Workflow
- 1. **Generate an image with Ideogram:**
- <!-- end list -->
- ```typescript
- // Using ideogram-mcp-server
- {
- name: 'generate_image',
- arguments: {
- prompt: "A futuristic dashboard design with neon accents",
- aspect_ratio: "16:9"
- }
- }
- // Returns: { image_url: "https://..." }
- ```
- 2. **Attach the generated image to a Trello card:**
- <!-- end list -->
- ```typescript
- // Using trello-mcp-server
- {
- name: 'attach_image_to_card',
- arguments: {
- cardId: "your-card-id",
- imageUrl: "https://...", // URL from Ideogram
- name: "Dashboard Mockup v1"
- }
- }
- ```
- #### Setting up both servers
- Add both servers to your Claude Desktop configuration. Use `bunx` for the fastest startup.
- ```json
- {
- "mcpServers": {
- "trello": {
- "command": "bunx",
- "args": ["@delorenj/mcp-server-trello"],
- "env": {
- "TRELLO_API_KEY": "your-trello-api-key",
- "TRELLO_TOKEN": "your-trello-token"
- }
- },
- "ideogram": {
- "command": "bunx",
- "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\!
- ## Rate Limiting
- The server implements a token bucket algorithm for rate limiting to comply with Trello's API limits:
- - 300 requests per 10 seconds per API key
- - 100 requests per 10 seconds per token
- Rate limiting is handled automatically, and requests will be queued if limits are reached.
- ## Error Handling
- The server provides detailed error messages for various scenarios:
- - Invalid input parameters
- - Rate limit exceeded
- - API authentication errors
- - Network issues
- - Invalid board/list/card IDs
- ## Development
- ### Prerequisites
- - [Bun](https://bun.sh) (v1.0.0 or higher)
- ### Setup
- 1. Clone the repository
- <!-- end list -->
- ```bash
- git clone https://github.com/delorenj/mcp-server-trello
- cd mcp-server-trello
- ```
- 2. Install dependencies
- <!-- end list -->
- ```bash
- bun install
- ```
- 3. Build the project
- <!-- end list -->
- ```bash
- bun run build
- ```
- ## Running tests
- To run the tests, run the following command:
- ```bash
- bun test
- ```
- ## Running evals
- 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 `bunx` command. Full documentation can be found [here](https://www.mcpevals.io/docs).
- ```bash
- OPENAI_API_KEY=your-key bunx mcp-eval src/evals/evals.ts src/index.ts
- ```
- ## Contributing
- Contributions are welcome\!
- ## License
- This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
- ## Acknowledgments
- - Built with the [Model Context Protocol SDK](https://github.com/modelcontextprotocol/typescript-sdk)
- - Uses the [Trello REST API](https://developer.atlassian.com/cloud/trello/rest/)
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.