Skip to content
Back to search

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.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/delorenj--mcp-server-trello/badge.svg)](/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

i

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)

  1. # MCP Server Trello
  2. [![Verified on MseeP](https://mseep.ai/badge.svg)](https://mseep.ai/app/27359682-7632-4ba7-981d-7dfecadf1c4b)
  3. [![MCP Registry](https://img.shields.io/badge/MCP-Registry-blue)](https://registry.modelcontextprotocol.io/servers/io.github.delorenj/mcp-server-trello)
  4. [![npm version](https://badge.fury.io/js/%40delorenj%2Fmcp-server-trello.svg)](https://badge.fury.io/js/%40delorenj%2Fmcp-server-trello)
  5. <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>
  6. 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.
  7. ## Highlights
  8. - **Acceptance criteria, natively**: `get_acceptance_criteria` pulls a card's AC checklist straight into your agent's context — no competitor offers it.
  9. - **Watch anything**: `watch_card` and `watch_list` route card and list activity into your Trello notifications.
  10. - **Full list management**: create, update, reorder (`update_list_position`), and archive lists.
  11. - **Board and workspace switching on the fly**: no restarts, no config edits.
  12. - **Rate limiting handled for you**: respects Trello's API limits automatically (300 req/10s per key, 100 req/10s per token).
  13. - **Bun-powered**: fast startup and a 2.8-4.4x performance boost over the old Node build. `npx` and `npm` work too.
  14. ## Changelog
  15. For a detailed list of changes, see [CHANGELOG.md](CHANGELOG.md).
  16. ## Features
  17. - **Full Trello Board Integration**: Interact with cards, lists, and board activities
  18. - **Acceptance Criteria Extraction**: Pull a card's acceptance criteria checklist directly into agent context
  19. - **Checklist Intelligence**: Query checklist items by name or description, track completion, manage items
  20. - **Complete Card Data Extraction**: Fetch all card details including checklists, attachments, labels, members, and comments
  21. - **💬 Comment Management**: Add, update, delete, and retrieve comments on cards
  22. - **Activity Subscriptions**: Watch cards and lists so their activity surfaces in Trello notifications
  23. - **List Management**: Create, update, reorder, and archive lists
  24. - **File Attachments**: Attach any type of file to cards (PDFs, documents, videos, images, etc.) from URLs
  25. - **Custom Fields**: Read board custom field definitions and update card values
  26. - **Built-in Rate Limiting**: Respects Trello's API limits (300 requests/10s per API key, 100 requests/10s per token)
  27. - **Type-Safe Implementation**: Written in TypeScript with comprehensive type definitions
  28. - **Input Validation**: Robust validation for all API inputs
  29. - **Error Handling**: Graceful error handling with informative messages
  30. - **Dynamic Board Selection**: Switch between boards and workspaces without restarting
  31. - **Markdown Formatting**: Export card data in human-readable markdown format
  32. ## Installation
  33. 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.
  34. ### Quickstart (Claude Desktop, Cursor, and other MCP clients)
  35. Add the server to your client's MCP configuration:
  36. ```json
  37. {
  38. "mcpServers": {
  39. "trello": {
  40. "command": "bunx",
  41. "args": ["@delorenj/mcp-server-trello"],
  42. "env": {
  43. "TRELLO_API_KEY": "your-trello-api-key",
  44. "TRELLO_TOKEN": "your-trello-token"
  45. }
  46. }
  47. }
  48. }
  49. ```
  50. `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.
  51. ### Claude Code
  52. Register the server with the CLI:
  53. ```bash
  54. claude mcp add trello \
  55. --env TRELLO_API_KEY=your-trello-api-key \
  56. --env TRELLO_TOKEN=your-trello-token \
  57. -- bunx @delorenj/mcp-server-trello
  58. ```
  59. ### MCP Registry
  60. 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.
  61. ### Agent skill package (optional)
  62. This repository also ships a **BMAD-compatible skill package** for the
  63. Trello MCP server. Install the `skill/` directory through your agent's skill
  64. management workflow, or place it in the agent's skills directory.
  65. When an agent activates the skill, it follows `skill/SKILL.md`. On first use,
  66. the agent runs the bundled installer:
  67. ```bash
  68. bash skill/scripts/install.sh
  69. ```
  70. The installer builds the MCP server from `skill/assets/source/` when Bun is
  71. available. If Bun is unavailable, it falls back to the published Smithery
  72. install path for `@delorenj/mcp-server-trello` and creates the same local
  73. `build/index.js` command path used by the skill activation check.
  74. ## Skill package structure
  75. The skill is the agent-facing entry point for this repository.
  76. - `skill/SKILL.md`: Activation, routing, and agent workflow rules.
  77. - `skill/scripts/install.sh`: First-run installer for the bundled server.
  78. - `skill/references/trello-mcp/`: Focused references for setup, tools,
  79. workflows, and gotchas.
  80. - `skill/assets/source/`: Bundled MCP server source used for local builds.
  81. For AI agents, start with `skill/SKILL.md` rather than this README. The README
  82. is the human-facing overview; the skill references are the operational surface
  83. for tool selection and Trello workflow rules.
  84. Maintainers can refresh the bundled source before packaging with:
  85. ```bash
  86. mise run package
  87. ```
  88. ## Configuration
  89. ### Environment Variables
  90. The server can be configured using environment variables. Create a `.env` file in the root directory with the following variables:
  91. ```env
  92. # Required: Your Trello API credentials
  93. TRELLO_API_KEY=your-api-key
  94. TRELLO_TOKEN=your-token
  95. # Optional (Deprecated): Default board ID (can be changed later using set_active_board)
  96. TRELLO_BOARD_ID=your-board-id
  97. # Optional: Initial workspace ID (can be changed later using set_active_workspace)
  98. TRELLO_WORKSPACE_ID=your-workspace-id
  99. # Optional: HTTPS proxy URL (for corporate proxies or restricted networks)
  100. https_proxy=http://your-proxy:8080
  101. # Optional: Restrict access to specific workspaces (comma-separated IDs)
  102. # If set, only the listed workspaces will be accessible via MCP tools
  103. TRELLO_ALLOWED_WORKSPACES=workspace-id-1,workspace-id-2
  104. ```
  105. > **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.
  106. You can get these values from:
  107. - API Key: [https://trello.com/app-key](https://trello.com/app-key)
  108. - Token: Generate using your API key
  109. - Board ID (optional, deprecated): Found in the board URL (e.g., `https://trello.com/b/abc123/example-board`)
  110. - Workspace ID: Found in workspace settings or using `list_workspaces` tool
  111. ### Board and Workspace Management
  112. Starting with version 0.3.0, the MCP server supports multiple ways to work with boards:
  113. 1. **Multi-board support**: All methods now accept an optional `boardId` parameter
  114.    - Omit `TRELLO_BOARD_ID` and provide `boardId` in each API call
  115.    - Set `TRELLO_BOARD_ID` as default and optionally override with `boardId` parameter
  116. 2. **Dynamic board selection**: Use workspace management tools
  117.    - The `TRELLO_BOARD_ID` in your `.env` file is used as the initial/default board ID
  118.    - You can change the active board at any time using the `set_active_board` tool
  119.    - The selected board persists between server restarts (stored in `~/.trello-mcp/config.json`)
  120.    - Similarly, you can set and persist an active workspace using `set_active_workspace`
  121. This allows you to work with multiple boards and workspaces without restarting the server.
  122. ### Workspace Access Restriction
  123. You can optionally restrict MCP access to specific workspaces using the `TRELLO_ALLOWED_WORKSPACES` environment variable. This is useful for:
  124. - **Security**: Limiting AI agent access to only approved workspaces
  125. - **Multi-tenant setups**: Ensuring agents only access relevant workspaces
  126. - **Testing**: Isolating test environments from production data
  127. When `TRELLO_ALLOWED_WORKSPACES` is set:
  128. - `list_workspaces` only returns workspaces in the allowed list
  129. - `list_boards` only returns boards from allowed workspaces
  130. - `set_active_workspace` rejects workspaces not in the allowed list
  131. - `list_boards_in_workspace` rejects non-allowed workspace IDs
  132. - `create_board` rejects creation in non-allowed workspaces
  133. Example configuration:
  134. ```bash
  135. # Only allow access to two specific workspaces
  136. TRELLO_ALLOWED_WORKSPACES=697c549ce04dc460af133a75,5f8a3b2c1d4e5f6a7b8c9d0e
  137. ```
  138. If `TRELLO_ALLOWED_WORKSPACES` is not set or empty, all workspaces the token has access to will be available (default behaviour).
  139. #### Example Workflow
  140. 1. Start by listing available boards:
  141. <!-- end list -->
  142. ```typescript
  143. {
  144.   name: 'list_boards',
  145.   arguments: {}
  146. }
  147. ```
  148. 2. Set your active board:
  149. <!-- end list -->
  150. ```typescript
  151. {
  152.   name: 'set_active_board',
  153.   arguments: {
  154.     boardId: "abc123"  // ID from list_boards response
  155.   }
  156. }
  157. ```
  158. 3. List workspaces if needed:
  159. <!-- end list -->
  160. ```typescript
  161. {
  162.   name: 'list_workspaces',
  163.   arguments: {}
  164. }
  165. ```
  166. 4. Set active workspace if needed:
  167. <!-- end list -->
  168. ```typescript
  169. {
  170.   name: 'set_active_workspace',
  171.   arguments: {
  172.     workspaceId: "xyz789"  // ID from list_workspaces response
  173.   }
  174. }
  175. ```
  176. 5. Check current active board info:
  177. <!-- end list -->
  178. ```typescript
  179. {
  180.   name: 'get_active_board_info',
  181.   arguments: {}
  182. }
  183. ```
  184. ## Date Format Guidelines
  185. When working with dates in the Trello MCP server, please note the different format requirements:
  186. - **Due Date (`dueDate`)**: Accepts full ISO 8601 format with time (e.g., `2023-12-31T12:00:00Z`)
  187. - **Start Date (`start`)**: Accepts date only in YYYY-MM-DD format (e.g., `2025-08-05`)
  188. This distinction follows Trello's API conventions where start dates are day-based markers while due dates can include specific times.
  189. ## Available Tools
  190. ### Checklist Management Tools 🆕
  191. #### get\_checklist\_items
  192. Get all items from a checklist by name.
  193. ```typescript
  194. {
  195.   name: 'get_checklist_items',
  196.   arguments: {
  197.     name: string,        // Name of the checklist to retrieve items from
  198.     boardId?: string     // Optional: ID of the board (uses default if not provided)
  199.   }
  200. }
  201. ```
  202. #### add\_checklist\_item
  203. Add a new item to an existing checklist.
  204. ```typescript
  205. {
  206.   name: 'add_checklist_item',
  207.   arguments: {
  208.     text: string,           // Text content of the checklist item
  209.     checkListName: string,  // Name of the checklist to add the item to
  210.     boardId?: string        // Optional: ID of the board (uses default if not provided)
  211.   }
  212. }
  213. ```
  214. #### find\_checklist\_items\_by\_description
  215. Search for checklist items containing specific text.
  216. ```typescript
  217. {
  218. name: 'find_checklist_items_by_description',
  219.   arguments: {
  220.     description: string,  // Text to search for in checklist item descriptions
  221.     boardId?: string      // Optional: ID of the board (uses default if not provided)
  222. }
  223. }
  224. ```
  225. #### get\_acceptance\_criteria
  226. 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.
  227. ```typescript
  228. {
  229.   name: 'get_acceptance_criteria',
  230.   arguments: {
  231.     cardId?: string,  // Optional: ID of the card to scope the search to (recommended to avoid ambiguity)
  232.     boardId?: string  // Optional: ID of the board (uses default if not provided)
  233.   }
  234. }
  235. ```
  236. On a match, returns:
  237. ```typescript
  238. {
  239.   found: true,
  240.   items: CheckListItem[],    // All items of the matching checklist(s), in Trello's order
  241.   unmet: CheckListItem[],    // The incomplete subset of items
  242.   percentComplete: number,  // Rounded percentage complete; 0 when there are no items
  243.   matchedChecklistName: string  // The checklist name as written on the board, original casing
  244. }
  245. ```
  246. 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":
  247. ```typescript
  248. {
  249.   found: false,
  250.   reason: string,    // Human-readable explanation naming the aliases that were tried
  251.   availableChecklists: string[]  // Names of the checklists that do exist in the searched scope
  252. }
  253. ```
  254. A checklist that matches but has no items returns `found: true` with `items: []`, which is distinct from the not-found response above.
  255. #### get\_checklist\_by\_name
  256. Get a complete checklist with all items and completion percentage.
  257. ```typescript
  258. {
  259.   name: 'get_checklist_by_name',
  260.   arguments: {
  261.     name: string,     // Name of the checklist to retrieve
  262.     boardId?: string  // Optional: ID of the board (uses default if not provided)
  263.   }
  264. }
  265. ```
  266. **Returns:** `CheckList` object with:
  267. - `id`: Checklist identifier
  268. - `name`: Checklist name
  269. - `items`: Array of `CheckListItem` objects
  270. - `percentComplete`: Completion percentage (0-100)
  271. #### update\_checklist\_item
  272. Update an existing checklist item.
  273. ```typescript
  274. {
  275. name: 'update_checklist_item',
  276. arguments: {
  277. cardId: string, // ID of the card containing the checklist item
  278. checkItemId: string, // ID of the checklist item to update
  279. name?: string, // Optional: new checklist item text
  280. state?: 'complete' | 'incomplete', // Optional: new checklist item state
  281. pos?: number | 'top' | 'bottom', // Optional: new checklist item position
  282. due?: string | null, // Optional: ISO 8601 due date, or null to clear it
  283. dueReminder?: number | null, // Optional: reminder offset in minutes, or null to clear it
  284. idMember?: string | null // Optional: member ID to assign, or null to clear it
  285. }
  286. }
  287. ```
  288. #### delete\_checklist\_item
  289. Delete an existing checklist item.
  290. ```typescript
  291. {
  292. name: 'delete_checklist_item',
  293. arguments: {
  294. cardId: string, // ID of the card containing the checklist item
  295. checkItemId: string // ID of the checklist item to delete
  296. }
  297. }
  298. ```
  299. ### get\_card 🆕
  300. Get comprehensive details of a specific Trello card with human-level parity.
  301. ```typescript
  302. {
  303.   name: 'get_card',
  304.   arguments: {
  305.     cardId: string,          // ID of the Trello card (short ID like 'FdhbArbK' or full ID)
  306.     includeMarkdown?: boolean // Return formatted markdown instead of JSON (default: false)
  307.   }
  308. }
  309. ```
  310. **Returns:** Complete card data including:
  311. - ✅ Checklists with item states and assignments
  312. - 📎 Attachments with previews and metadata
  313. - 🏷️ Labels with names and colors
  314. - 👥 Assigned members
  315. - 💬 Comments and activity
  316. - 📊 Statistics (badges)
  317. - 🎨 Cover images
  318. - 📍 Board and list context
  319. ### get\_cards\_by\_list\_id
  320. Fetch all cards from a specific list.
  321. ```typescript
  322. {
  323.   name: 'get_cards_by_list_id',
  324.   arguments: {
  325.     boardId?: string, // Optional: ID of the board (uses default if not provided)
  326.     listId: string    // ID of the Trello list
  327.   }
  328. }
  329. ```
  330. ### get\_lists
  331. Retrieve all lists from a board.
  332. ```typescript
  333. {
  334.   name: 'get_lists',
  335.   arguments: {
  336.     boardId?: string  // Optional: ID of the board (uses default if not provided)
  337.   }
  338. }
  339. ```
  340. ### get\_recent\_activity
  341. Fetch recent activity on a board.
  342. ```typescript
  343. {
  344.   name: 'get_recent_activity',
  345.   arguments: {
  346.     boardId?: string, // Optional: ID of the board (uses default if not provided)
  347.     limit?: number    // Optional: Number of activities to fetch (default: 10)
  348.   }
  349. }
  350. ```
  351. ### add\_card\_to\_list
  352. Add a new card to a specified list.
  353. ```typescript
  354. {
  355.   name: 'add_card_to_list',
  356.   arguments: {
  357.     boardId?: string,     // Optional: ID of the board (uses default if not provided)
  358.     listId: string,       // ID of the list to add the card to
  359.     name: string,         // Name of the card
  360.     description?: string, // Optional: Description of the card
  361.   mbs; dueDate?: string,     // Optional: Due date (ISO 8601 format with time)
  362.     start?: string,       // Optional: Start date (YYYY-MM-DD format, date only)
  363.     labels?: string[]     // Optional: Array of label IDs
  364.   }
  365. }
  366. ```
  367. ### update\_card\_details
  368. Update an existing card's details.
  369. ```typescript
  370. {
  371.   name: 'update_card_details',
  372.   arguments: {
  373.     boardId?: string,     // Optional: ID of the board (uses default if not provided)
  374.     cardId: string,       // ID of the card to update
  375.     name?: string,        // Optional: New name for the card
  376.     description?: string, // Optional: New description
  377.     dueDate?: string,     // Optional: New due date (ISO 8601 format with time)
  378.     start?: string,       // Optional: New start date (YYYY-MM-DD format, date only)
  379.     dueComplete?: boolean,// Optional: Mark the due date as complete (true) or incomplete (false)
  380.     labels?: string[]     // Optional: New array of label IDs
  381.   }
  382. }
  383. ```
  384. ### archive\_card
  385. Send a card to the archive.
  386. ```typescript
  387. {
  388.   name: 'archive_card',
  389.   arguments: {
  390.     boardId?: string, // Optional: ID of the board (uses default if not provided)
  391.     cardId: string    // ID of the card to archive
  392.   }
  393. }
  394. ```
  395. ### add\_list\_to\_board
  396. Add a new list to a board.
  397. ```typescript
  398. {
  399. name: 'add_list_to_board',
  400.   arguments: {
  401.     boardId?: string, // Optional: ID of the board (uses default if not provided)
  402.     name: string      // Name of the new list
  403.   }
  404. }
  405. ```
  406. ### archive\_list
  407. Send a list to the archive.
  408. ```typescript
  409. {
  410.   name: 'archive_list',
  411.   arguments: {
  412.     boardId?: string, // Optional: ID of the board (uses default if not provided)
  413.     listId: string    // ID of the list to archive
  414.   }
  415. }
  416. ```
  417. ### update\_list
  418. Update a list's name, archive state, subscription state, or board. Use `update_list_position` to reorder lists within a board.
  419. ```typescript
  420. {
  421. name: 'update_list',
  422. arguments: {
  423. listId: string, // ID of the list to update
  424. name?: string, // Optional: New name for the list
  425. closed?: boolean, // Optional: Whether to close (archive) the list
  426. subscribed?: boolean, // Optional: Whether to subscribe to the list
  427. idBoard?: string // Optional: ID of a board to move the list to
  428. }
  429. }
  430. ```
  431. ### update\_list\_position
  432. 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.
  433. ```typescript
  434. {
  435. name: 'update_list_position',
  436. arguments: {
  437. listId: string, // ID of the list to reposition
  438. position: string // "top", "bottom", or a positive numeric string (e.g. "1536")
  439. }
  440. }
  441. ```
  442. ### get\_my\_cards
  443. Fetch all cards assigned to the current user.
  444. ```typescript
  445. {
  446.   name: 'get_my_cards',
  447.   arguments: {}
  448. }
  449. ```
  450. ### move\_card
  451. Move a card to a different list.
  452. ```typescript
  453. {
  454.   name: 'move_card',
  455.   arguments: {
  456.     boardId?: string,  // Optional: ID of the target board (uses default if not provided)
  457. s;   cardId: string,    // ID of the card to move
  458.     listId: string     // ID of the target list
  459.   }
  460. }
  461. ```
  462. ### attach\_image\_to\_card
  463. Attach an image to a card directly from a URL.
  464. ```typescript
  465. {
  466.   name: 'attach_image_to_card',
  467.   arguments: {
  468.     boardId?: string, // Optional: ID of the board (uses default if not provided)
  469.     cardId: string,  // ID of the card to attach the image to
  470.     imageUrl: string, // URL of the image to attach
  471.     name?: string     // Optional: Name for the attachment (defaults to "Image Attachment")
  472.   }
  473. }
  474. ```
  475. ### attach\_file\_to\_card
  476. Attach any type of file to a card from a URL or a local file path (e.g., `file:///path/to/your/file.pdf`).
  477. ```typescript
  478. {
  479.   name: 'attach_file_to_card',
  480. arguments: {
  481.     boardId?: string,  // Optional: ID of the board (uses default if not provided)
  482.     cardId: string,s;   // ID of the card to attach the file to
  483.     fileUrl: string,   // URL or local file path (using the file:// protocol) of the file to attach
  484.     name?: string,     // Optional: Name for the attachment (defaults to the file name for local files)
  485.     mimeType?: string  // Optional: MIME type (e.g., "application/pdf", "text/plain", "video/mp4")
  486.   }
  487. }
  488. ```
  489. ### download\_attachment
  490. Download an attachment from a card by ID. Attachment IDs are available in the `attachments` array returned by `get_card`.
  491. ```typescript
  492. {
  493. name: 'download_attachment',
  494. arguments: {
  495. cardId: string, // ID of the card containing the attachment
  496. attachmentId: string // ID of the attachment to download
  497. }
  498. }
  499. ```
  500. **Returns:** For image attachments (`image/*`), returns the image as inline viewable data. For all other file types, returns a JSON object with:
  501. - `fileName`: Original filename
  502. - `mimeType`: MIME type of the file
  503. - `data`: Base64-encoded file contents
  504. ### Comment Management Tools
  505. #### add\_comment
  506. Add a comment to a Trello card.
  507. ```typescript
  508. {
  509. name: 'add_comment',
  510. arguments: {
  511. cardId: string, // ID of the card to comment on
  512. text: string // The text of the comment to add
  513. }
  514. }
  515. ```
  516. #### update\_comment
  517. Update an existing comment on a card.
  518. ```typescript
  519. {
  520. name: 'update_comment',
  521. arguments: {
  522. commentId: string, // ID of the comment to change
  523. text: string // The new text of the comment
  524. }
  525. }
  526. ```
  527. #### delete\_comment
  528. Delete a comment from a card.
  529. ```typescript
  530. {
  531. name: 'delete_comment',
  532. arguments: {
  533. commentId: string // ID of the comment to delete
  534. }
  535. }
  536. ```
  537. #### get\_card\_comments
  538. Retrieve all comments from a specific card without fetching all card data.
  539. ```typescript
  540. {
  541. name: 'get_card_comments',
  542. arguments: {
  543. cardId: string, // ID of the card to get comments from
  544. limit?: number // Optional: Maximum number of comments to retrieve (default: 100)
  545. }
  546. }
  547. ```
  548. ### list\_boards
  549. List all boards the user has access to.
  550. ```typescript
  551. {
  552.   name: 'list_boards',
  553.   arguments: {}
  554. }
  555. ```
  556. ### set\_active\_board
  557. Set the active board for future operations.
  558. ```typescript
  559. {
  560.   name: 'set_active_board',
  561.   arguments: {
  562.     boardId: string  // ID of the board to set as active
  563.   }
  564. }
  565. ```
  566. ### list\_workspaces
  567. List all workspaces the user has access to.
  568. ```typescript
  569. {
  570. s; name: 'list_workspaces',
  571.   arguments: {}
  572. }
  573. ```
  574. ### set\_active\_workspace
  575. Set the active workspace for future operations.
  576. ```typescript
  577. {
  578.   name: 'set_active_workspace',
  579.   arguments: {
  580.     workspaceId: string  // ID of the workspace to set as active
  581.   }
  582. }
  583. ```
  584. ### list\_boards\_in\_workspace
  585. List all boards in a specific workspace.
  586. ```typescript
  587. {
  588.   name: 'list_boards_in_workspace',
  589.   arguments: {
  590.     workspaceId: string  // ID of the workspace to list boards from
  591.   }
  592. }
  593. ```
  594. ### get\_active\_board\_info
  595. Get information about the currently active board.
  596. ```typescript
  597. {
  598. s; name: 'get_active_board_info',
  599.   arguments: {}
  600. }
  601. ```
  602. ### Custom Field Management Tools
  603. > **Note:** Custom fields require Trello Standard plan or higher.
  604. #### get\_board\_custom\_fields
  605. Get all custom field definitions on a board. For dropdown/list fields, also returns the available options with their IDs.
  606. ```typescript
  607. {
  608. name: 'get_board_custom_fields',
  609. arguments: {
  610. boardId?: string // Optional: ID of the board (uses default if not provided)
  611. }
  612. }
  613. ```
  614. **Returns:** Array of custom field definitions including:
  615. - Field ID, name, type (`text`, `number`, `checkbox`, `date`, `list`)
  616. - For `list` type fields: available options with IDs (use these IDs when setting values)
  617. #### update\_card\_custom\_field
  618. Set or clear a custom field value on a card.
  619. ```typescript
  620. {
  621. name: 'update_card_custom_field',
  622. arguments: {
  623. cardId: string, // ID of the card to update
  624. customFieldId: string,// ID of the custom field definition
  625. type: string, // Field type: 'text' | 'number' | 'checkbox' | 'date' | 'list' | 'clear'
  626. value?: string // The value to set (not needed when type is 'clear')
  627. }
  628. }
  629. ```
  630. **Value format by type:**
  631. - `text`: any string
  632. - `number`: numeric string (e.g. `"42.5"`)
  633. - `checkbox`: `"true"` or `"false"`
  634. - `date`: ISO 8601 string (e.g. `"2025-12-31T00:00:00.000Z"`)
  635. - `list`: option ID from `get_board_custom_fields`
  636. - `clear`: omit value to remove the field value
  637. ## Integration Examples
  638. ### 🎨 Pairing with Ideogram MCP Server
  639. 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\!
  640. #### Example Workflow
  641. 1. **Generate an image with Ideogram:**
  642. <!-- end list -->
  643. ```typescript
  644. // Using ideogram-mcp-server
  645. {
  646.   name: 'generate_image',
  647.   arguments: {
  648.     prompt: "A futuristic dashboard design with neon accents",
  649.     aspect_ratio: "16:9"
  650.   }
  651. }
  652. // Returns: { image_url: "https://..." }
  653. ```
  654. 2. **Attach the generated image to a Trello card:**
  655. <!-- end list -->
  656. ```typescript
  657. // Using trello-mcp-server
  658. {
  659.   name: 'attach_image_to_card',
  660.   arguments: {
  661.     cardId: "your-card-id",
  662.     imageUrl: "https://...", // URL from Ideogram
  663.     name: "Dashboard Mockup v1"
  664.   }
  665. }
  666. ```
  667. #### Setting up both servers
  668. Add both servers to your Claude Desktop configuration. Use `bunx` for the fastest startup.
  669. ```json
  670. {
  671.   "mcpServers": {
  672.     "trello": {
  673.       "command": "bunx",
  674.       "args": ["@delorenj/mcp-server-trello"],
  675.   "env": {
  676.         "TRELLO_API_KEY": "your-trello-api-key",
  677.         "TRELLO_TOKEN": "your-trello-token"
  678.       }
  679.     },
  680.     "ideogram": {
  681.       "command": "bunx",
  682.       "args": ["@flowluap/ideogram-mcp-server"],
  683.       "env": {
  684.         "IDEOGRAM_API_KEY": "your-ideogram-api-key"
  685.       }
  686.     }
  687.   }
  688. }
  689. ```
  690. Now you can seamlessly create visual content and organize it in Trello, all within Claude\!
  691. ## Rate Limiting
  692. The server implements a token bucket algorithm for rate limiting to comply with Trello's API limits:
  693. - 300 requests per 10 seconds per API key
  694. - 100 requests per 10 seconds per token
  695. Rate limiting is handled automatically, and requests will be queued if limits are reached.
  696. ## Error Handling
  697. The server provides detailed error messages for various scenarios:
  698. - Invalid input parameters
  699. - Rate limit exceeded
  700. - API authentication errors
  701. - Network issues
  702. - Invalid board/list/card IDs
  703. ## Development
  704. ### Prerequisites
  705. - [Bun](https://bun.sh) (v1.0.0 or higher)
  706. ### Setup
  707. 1. Clone the repository
  708. <!-- end list -->
  709. ```bash
  710. git clone https://github.com/delorenj/mcp-server-trello
  711. cd mcp-server-trello
  712. ```
  713. 2. Install dependencies
  714. <!-- end list -->
  715. ```bash
  716. bun install
  717. ```
  718. 3. Build the project
  719. <!-- end list -->
  720. ```bash
  721. bun run build
  722. ```
  723. ## Running tests
  724. To run the tests, run the following command:
  725. ```bash
  726. bun test
  727. ```
  728. ## Running evals
  729. 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).
  730. ```bash
  731. OPENAI_API_KEY=your-key bunx mcp-eval src/evals/evals.ts src/index.ts
  732. ```
  733. ## Contributing
  734. Contributions are welcome\!
  735. ## License
  736. This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
  737. ## Acknowledgments
  738. - Built with the [Model Context Protocol SDK](https://github.com/modelcontextprotocol/typescript-sdk)
  739. - Uses the [Trello REST API](https://developer.atlassian.com/cloud/trello/rest/)

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.