Trello MCP Server

什么是 Trello MCP Server？

Trello MCP Server 是一个社区开发的 trello mcp 集成，它通过 Model Context Protocol 让 AI 智能体读取和更新你的 Trello 看板、列表、卡片、检查清单、评论、附件和自定义字段。

它由 delorenj 维护，以 @delorenj/mcp-server-trello 的名称发布在 npm 上，采用 MIT 许可证，并以 io.github.delorenj/mcp-server-trello 的名称收录在官方 MCP Registry 中。它并非由 Trello 或 Atlassian 开发或提供支持。根据 README，它提供 57 个工具，内置速率限制，基于 Bun 构建，并通过 stdio 在本地运行。

如何使用 Trello MCP Server？

前置条件：

• 一个 Trello 账号，以及从 trello.com/app-key 获取的 API key。
• 一个 Trello token，在同一页面使用你的 API key 生成。
• Bun（用于 bunx）或 Node.js（用于 npx）。README 提到 bunx 启动最快，npx 的效果完全相同。

环境变量：

# Required
TRELLO_API_KEY=your-api-key
TRELLO_TOKEN=your-token

# Optional (deprecated): default board ID, can be changed later with set_active_board
TRELLO_BOARD_ID=your-board-id

# Optional: initial workspace ID, can be changed later with set_active_workspace
TRELLO_WORKSPACE_ID=your-workspace-id

# Optional: HTTPS proxy
https_proxy=http://your-proxy:8080

# Optional: restrict access to specific workspaces (comma-separated IDs)
TRELLO_ALLOWED_WORKSPACES=workspace-id-1,workspace-id-2

Claude Code

使用 CLI 注册 trello mcp server：

claude mcp add trello \
  --env TRELLO_API_KEY=your-trello-api-key \
  --env TRELLO_TOKEN=your-trello-token \
  -- bunx @delorenj/mcp-server-trello

Claude Desktop

将以下内容添加到 Claude Desktop 的 MCP 配置中，然后重启应用：

{
  "mcpServers": {
    "trello": {
      "command": "bunx",
      "args": ["@delorenj/mcp-server-trello"],
      "env": {
        "TRELLO_API_KEY": "your-trello-api-key",
        "TRELLO_TOKEN": "your-trello-token"
      }
    }
  }
}

Cursor

README 中的快速开始配置同样适用于 Cursor 和其他 MCP 客户端。把上面的 mcpServers 配置块添加到 Cursor 的 MCP 配置中即可。如果想用 npm 代替 Bun，把 bunx 换成 npx。

连接成功后，典型的第一步是：调用 list_boards，用 set_active_board 选择一个看板，再用 get_active_board_info 确认。

Trello MCP Server 的主要功能

• 完整的看板覆盖：支持卡片、列表、检查清单、标签、成员、评论、附件、自定义字段和看板动态。
• 提取验收标准：get_acceptance_criteria 会查找名为 Acceptance Criteria、AC、DoD 或 Definition of Done 的检查清单，返回其中的条目、未完成条目和完成百分比。
• 动态切换看板和工作区：无需重启即可更换当前看板或工作区，所选内容保存在 ~/.trello-mcp/config.json 中。
• 工作区白名单：TRELLO_ALLOWED_WORKSPACES 限定智能体可以列出、打开或在其中创建看板的工作区。
• 内置速率限制：采用令牌桶算法，遵守 Trello 的限制（每个 API key 每 10 秒 300 次请求，每个 token 每 10 秒 100 次），达到限制时请求会排队。
• 文件附件：可从 URL 或本地 file:// 路径附加文件，也可以下载附件。
• Markdown 输出：get_card 搭配 includeMarkdown 可以把卡片返回为易读的 Markdown。
• 代理支持：通过 https_proxy 或 HTTPS_PROXY 转发 Trello API 流量。

Trello MCP Server 工具

• 看板与工作区：list_boards、set_active_board、get_active_board_info、list_workspaces、set_active_workspace 和 list_boards_in_workspace 负责导航。其他大多数工具都接受可选的 boardId，因此一个会话中可以跨多个看板操作。
• 列表：get_lists、add_list_to_board、update_list、update_list_position（顶部、底部或分数位置）和 archive_list。
• 卡片：get_card 返回完整的卡片详情。get_cards_by_list_id、get_my_cards、add_card_to_list、update_card_details、move_card 和 archive_card 覆盖卡片的整个生命周期。截止日期使用带时间的 ISO 8601 格式，开始日期使用 YYYY-MM-DD。
• 检查清单：get_checklist_items、get_checklist_by_name、add_checklist_item、update_checklist_item、delete_checklist_item、find_checklist_items_by_description 和 get_acceptance_criteria。
• 评论：add_comment、update_comment、delete_comment 和 get_card_comments。
• 附件：attach_image_to_card、attach_file_to_card 和 download_attachment。
• 自定义字段：get_board_custom_fields 和 update_card_custom_field。自定义字段需要 Trello Standard 或更高级别的套餐。
• 动态：get_recent_activity，以及用于把动态推送到 Trello 通知中的 watch_card 和 watch_list。

Trello MCP Server 的使用场景

• 每日梳理：“列出所有分配给我的卡片，并标出哪些已逾期。”智能体会使用 get_my_cards。
• 迭代整理：“为这份需求文档中的每一项，在 Backlog 列表里创建卡片，截止日期设为下周五。”
• 完成标准检查：“卡片 FdhbArbK 上还有哪些验收标准没有满足？”智能体会使用 get_acceptance_criteria。
• 进度汇报：“总结 Marketing 看板最近的动态，并在发布卡片上发表一条评论。”
• 推进工作：“把 Review 列表中检查清单已全部完成的卡片移动到 Done。”
• 视觉素材：与其他 MCP 服务器搭配使用，例如 README 中提到的 Ideogram 服务器，然后用 attach_image_to_card 把生成的图片附加到卡片上。

Trello MCP Server 与替代方案对比

还有其他几个社区开发的 Trello MCP 服务器，包括一些 Python 实现，但收录在官方 MCP Registry 中的是 delorenj/mcp-server-trello。如果你的团队在其他工具中规划工作，可以对比用于 Jira 和 Confluence 的 Atlassian MCP Server、Asana MCP Server、ClickUp MCP Server 或 Linear MCP Server。这个服务器只在本地运行，使用你个人的 Trello key 和 token 认证，不是托管的 OAuth 服务。

Trello MCP Server 常见问题排查

• 认证错误：确认 TRELLO_API_KEY 和 TRELLO_TOKEN 都已设置，并且 token 是在 trello.com/app-key 上用同一个 API key 生成的。
• 看板不对或出现 “invalid ID” 错误：调用 list_boards 和 set_active_board，或显式传入 boardId。TRELLO_BOARD_ID 已弃用，而且当前看板会保存在 ~/.trello-mcp/config.json 中，旧的选择可能仍然生效。
• 看不到某个工作区或看板：如果设置了 TRELLO_ALLOWED_WORKSPACES，只有其中的工作区可以被列出或使用。添加对应 ID，或取消该变量。
• 请求卡住或变慢：触发 Trello 速率限制时，服务器会让请求排队，所以大批量任务会短暂暂停，而不是直接失败。
• 自定义字段更新失败：自定义字段需要 Trello Standard 或更高级别的套餐。对于 list 类型字段，请使用 get_board_custom_fields 返回的选项 ID。