Trello MCP 服务器

🔀 活跃分支。 这是 kocakli/Trello-Desktop-MCP 的一个维护版本，整合了来自整个分支生态系统（kevinhillinger、zonca、dbz-max、maks244、jantman、ThatIanMcShane、josh-argyle）的贡献。欢迎提交 PR —— 请参阅 Credits 查看每位贡献者带来的内容。已作为 atlassian-trello-mcp 发布在 npm 上。

一个适用于 Trello 的模型上下文协议 (MCP) 服务器，可与任何兼容 MCP 的客户端（如 Claude Desktop、Claude Code、Gemini CLI 等）配合使用。

提供 46 种工具，涵盖看板、卡片、列表、标签、清单、附件、成员、自定义字段和搜索功能。

快速入门

1. 获取 Trello API 凭据

• 访问 https://trello.com/app-key

• 复制您的 API Key

• 点击“Generate a Token”以获取读/写访问权限

2. 安装

最简单的方法是使用 npx —— 无需克隆，无需构建，直接运行：

npx atlassian-trello-mcp

或者从源码安装：

git clone https://github.com/agrath/Trello-Desktop-MCP.git
cd Trello-Desktop-MCP
npm install
npm run build

3. 配置您的 MCP 客户端

编辑您的配置文件：

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

• Windows: %APPDATA%\Claude\claude_desktop_config.json

• Linux: ~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "trello": {
      "command": "npx",
      "args": ["-y", "atlassian-trello-mcp"],
      "env": {
        "TRELLO_API_KEY": "your-api-key",
        "TRELLO_TOKEN": "your-token"
      }
    }
  }
}

claude mcp add trello -- npx -y atlassian-trello-mcp

设置环境变量 TRELLO_API_KEY 和 TRELLO_TOKEN，或者在每个请求中传递凭据。

编辑 ~/.gemini/settings.json：

{
  "mcpServers": {
    "trello": {
      "command": "npx",
      "args": ["-y", "atlassian-trello-mcp"],
      "env": {
        "TRELLO_API_KEY": "your-api-key",
        "TRELLO_TOKEN": "your-token"
      }
    }
  }
}

该服务器使用 stdio 传输。在设置环境变量的情况下运行：

TRELLO_API_KEY=your-key TRELLO_TOKEN=your-token npx atlassian-trello-mcp
# or, from a source clone:
TRELLO_API_KEY=your-key TRELLO_TOKEN=your-token node dist/index.js

Related MCP server: fastmcp-trello

凭据

凭据可以通过两种方式提供：

1. 环境变量（推荐）：设置 TRELLO_API_KEY 和 TRELLO_TOKEN

2. 按请求提供：将 apiKey 和 token 作为工具参数传递（会覆盖环境变量）

可用工具 (46)

看板与列表

卡片

评论与活动

标签

卡片成员

附件

清单

检查项

搜索

配置

只读模式

设置 TRELLO_READ_ONLY=true 以禁用所有写操作。仅提供读取/查询工具。

{
  "env": {
    "TRELLO_API_KEY": "your-key",
    "TRELLO_TOKEN": "your-token",
    "TRELLO_READ_ONLY": "true"
  }
}

紧凑模式

多个工具支持 compact 参数（默认：true），该参数返回最小字段以减小响应大小。设置 compact: false 可获取包括描述、标签、成员和自定义字段在内的完整详情。

支持紧凑模式的工具：get_board_details、trello_get_board_cards、trello_get_list_cards、trello_search。

图片附件下载

当调用 get_card 且卡片包含图片附件时，服务器会下载它们并将其作为内联 MCP 图片内容块与 JSON 一起返回，让客户端直接查看卡片图片。下载仅限于 Trello 托管的 URL (*.trello.com, trello-attachments.s3.amazonaws.com)，且每张图片上限为 5 MB，以降低 SSRF 和负载膨胀风险。

设置 TRELLO_DOWNLOAD_IMAGES=false（或 0/no/off）可完全禁用 —— 服务器将跳过额外的 getCardAttachments 调用并仅返回文本。默认开启。

日志记录

设置 TRELLO_MCP_LOGGING=true 以通过 Pino 启用基于文件的日志记录。日志写入 dist/logs/app.log。

开发

项目结构

src/
  index.ts              Entry point (credential injection, tool routing)
  server.ts             MCP server factory (read-only mode support)
  tools/
    boards.ts           Board tools (list, details, lists, filter)
    cards.ts            Card tools (CRUD, archive)
    lists.ts            List tools (cards, create list, comments)
    members.ts          Member tools (user boards, member details)
    search.ts           Search tool
    advanced.ts         Labels, attachments, members on cards, custom fields
    checklists.ts       Checklist and check item tools (13 tools)
  trello/
    client.ts           TrelloClient (API calls, retry, rate limiting)
  types/
    trello.ts           TypeScript interfaces
  utils/
    validation.ts       Zod schemas, extractCredentials, extractTrelloId
    logger.ts           Pino file logger
    health.ts           Health check utility
    appInsights.ts      Telemetry (no-op)
tests/
  validation.test.ts    Validation and credential extraction tests
  trelloClient.test.ts  API client tests (mocked fetch)
  tools.test.ts         Tool handler tests (mocked client)

构建与测试

npm install
npm run build
npm test
npm run type-check

关键模式

• ID 解析：所有工具均通过 extractTrelloId() 接受 Trello URL、短 ID 或完整的 24 字符十六进制 ID

• 凭据回退：extractCredentials() 首先检查参数，然后检查环境变量

• 带退避的重试：TrelloClient 在遇到 500/网络错误时会重试（3 次尝试，指数退避）

• 速率限制：从每个响应中提取并返回 x-rate-limit-* 标头

• 验证：Zod 模式在 API 调用前验证所有输入

贡献

欢迎提交 Pull Request，我们会积极审查。此分支由一位资深的 Trello 用户维护，因此功能会经过实际场景的测试。

如果您已经 fork 了原始项目并构建了一些有用的功能，请在此处提交 PR，而不是维护一个单独的分支 —— 让每个人都能从一个维护良好的项目中受益会更好。

如何贡献：

1. Fork 此仓库

2. 创建功能分支

3. 为新功能添加测试

4. 运行 npm test 和 npm run build

5. 提交包含清晰描述（内容和原因）的 Pull Request

致谢

本项目是 kocakli/Trello-Desktop-MCP 的一个分支。功能和想法整合自整个分支生态系统：

• kocakli -- 原始项目，与 MCP 客户端无关的重命名，stderr 日志修复

• kevinhillinger -- 凭据注入架构、标签删除、卡片成员管理、卡片归档、扩展的 TypeScript 类型、资源层

• zonca -- 带有环境变量回退的集中式凭据处理、标签管理工具、全面的单元测试、替换 any 的改进 TypeScript 类型

• dbz-max -- 自定义字段支持（看板自定义字段 + 卡片自定义字段项）

• maks244 -- 只读模式概念、按名称过滤列表、从遥测日志中剥离凭据

• jantman -- 修复了 MCP 客户端以字符串形式发送时被拒绝的数字 pos 值

• ThatIanMcShane -- 将 @modelcontextprotocol/sdk 从 1.0.4 升级到 1.29.0，以修复当前 Claude Code 版本的连接超时问题

• josh-argyle -- 在 get_card 响应中自动下载图片附件作为内联 MCP 图片内容块（在移植过程中添加了允许列表 + 大小限制）

许可证

MIT