Trello Mcp

Trello MCP

一个 Model Context Protocol (MCP) 服务，为任何兼容 MCP 的客户端提供全面的 Trello 集成 — 包括 Claude Desktop、Claude Code、Gemini CLI 等。该服务使 AI 助手能够通过安全的本地连接与 Trello 看板、卡片、列表等进行交互。

功能

🔍 搜索与发现

• 通用搜索：在所有 Trello 内容（看板、卡片、成员、组织）中进行搜索
• 用户看板：获取当前用户可访问的所有看板
• 看板详情：检索看板的详细信息，包括列表和卡片

📝 卡片管理

• 创建卡片：向任意列表添加新卡片，可附带描述、截止日期和指派
• 更新卡片：修改卡片属性，如名称、描述、截止日期和状态
• 移动卡片：在列表之间转移卡片以更新工作流状态
• 获取卡片详情：获取全面的卡片信息，包括成员、标签和检查清单

💬 协作

• 添加评论：在卡片上发布评论以进行团队沟通
• 成员管理：查看看板成员和成员详情
• 活动历史：跟踪卡片操作和变更

📋 组织

• 列表管理：创建新列表并获取特定列表中的卡片
• 标签：查看和管理看板标签以进行分类
• 检查清单：访问卡片检查清单和检查清单项目
• 附件：查看卡片附件和链接文件

安装

前提条件

• 已安装 Node.js 18+
• 一个兼容 MCP 的客户端（Claude Desktop、Claude Code、Gemini CLI 等）
• 具有 API 凭据的 Trello 账户

设置步骤

1. 克隆仓库

   git clone https://github.com/kocakli/trello-desktop-mcp.git
   cd trello-desktop-mcp
   

2. 安装依赖

   npm install
   

3. 构建项目

   npm run build
   

4. 获取 Trello API 凭据

   • 访问 https://trello.com/app-key
   • 复制你的 API Key
   • 生成一个 Token（永不过期，读写访问权限）

5. 配置你的 MCP 客户端

   在下方选择适用于你的客户端的说明：

   Claude Desktop

   编辑你的 Claude Desktop 配置文件：

   • macOS：~/Library/Application Support/Claude/claude_desktop_config.json
   • Windows：%APPDATA%\Claude\claude_desktop_config.json
   • Linux：~/.config/Claude/claude_desktop_config.json

   添加 Trello MCP 服务：

   {
     "mcpServers": {
       "trello": {
         "command": "node",
         "args": ["/absolute/path/to/trello-desktop-mcp/dist/index.js"],
         "env": {
           "TRELLO_API_KEY": "your-api-key-here",
           "TRELLO_TOKEN": "your-token-here"
         }
       }
     }
   }
   

   然后重启 Claude Desktop。

   Claude Code (CLI)

   使用 Claude Code 命令行添加该服务：

   claude mcp add trello -- node /absolute/path/to/trello-desktop-mcp/dist/index.js \
     -e TRELLO_API_KEY=your-api-key-here \
     -e TRELLO_TOKEN=your-token-here
   

   或将其添加到项目的 .mcp.json：

   {
     "mcpServers": {
       "trello": {
         "command": "node",
         "args": ["/absolute/path/to/trello-desktop-mcp/dist/index.js"],
         "env": {
           "TRELLO_API_KEY": "your-api-key-here",
           "TRELLO_TOKEN": "your-token-here"
         }
       }
     }
   }
   

   Gemini CLI

   编辑位于 ~/.gemini/settings.json 的 Gemini CLI 设置文件：

   {
     "mcpServers": {
       "trello": {
         "command": "node",
         "args": ["/absolute/path/to/trello-desktop-mcp/dist/index.js"],
         "env": {
           "TRELLO_API_KEY": "your-api-key-here",
           "TRELLO_TOKEN": "your-token-here"
         }
       }
     }
   }
   

   其他 MCP 客户端

   任何支持 stdio 传输的兼容 MCP 客户端都可以使用该服务。你需要将其配置为：

   1. 运行 node /absolute/path/to/trello-desktop-mcp/dist/index.js
   2. 设置环境变量 TRELLO_API_KEY 和 TRELLO_TOKEN

   有关确切的配置格式，请参阅你的客户端文档。

6. 重启你的 MCP 客户端以应用新配置。

可用工具

该 MCP 服务提供 19 个工具，分为三个阶段：

阶段 1：基础工具

• trello_search - 在所有 Trello 内容中进行通用搜索
• trello_get_user_boards - 获取当前用户可访问的所有看板
• get_board_details - 获取包含列表和卡片的详细看板信息
• get_card - 获取全面的卡片详情
• create_card - 在任意列表中创建新卡片

阶段 2：核心操作

• update_card - 更新卡片属性
• move_card - 在列表之间移动卡片
• trello_add_comment - 向卡片添加评论
• trello_get_list_cards - 获取特定列表中的所有卡片
• trello_create_list - 在看板上创建新列表

阶段 3：高级功能

• trello_get_board_cards - 获取看板中的所有卡片并支持筛选
• trello_get_card_actions - 获取卡片活动历史
• trello_get_card_attachments - 获取卡片附件
• trello_get_card_checklists - 获取卡片清单
• trello_get_board_members - 获取看板成员
• trello_get_board_labels - 获取看板标签
• trello_get_member - 获取成员详情

旧版工具（向后兼容）

• list_boards - 列出用户的看板
• get_lists - 获取看板中的列表

使用示例

配置完成后，你可以使用自然语言与 AI 助手交互来操作 Trello：

"Show me all my Trello boards"
"Create a new card called 'Update documentation' in the To Do list"
"Move card X from In Progress to Done"
"Add a comment to card Y saying 'This is ready for review'"
"Search for all cards with 'bug' in the title"
"Show me all cards assigned to me"

架构

MCP 协议

该服务实现了 Model Context Protocol（MCP），它提供：

• 标准化的工具发现与调用
• 类型安全的参数校验
• 结构化的错误处理
• 自动凭证管理

安全性

• API 凭证本地存储在 MCP 客户端的配置中
• 不会有凭证通过网络传输
• 所有 Trello API 调用均使用 HTTPS
• 遵守速率限制并具备自动重试逻辑

技术栈

• TypeScript 用于类型安全
• MCP SDK 用于协议实现
• Zod 用于模式校验
• Fetch API 用于 HTTP 请求

开发

项目结构

├── src/
│   ├── index.ts          # Main MCP server entry point
│   ├── server.ts         # Alternative server implementation
│   ├── tools/            # Tool implementations
│   │   ├── boards.ts     # Board-related tools
│   │   ├── cards.ts      # Card-related tools
│   │   ├── lists.ts      # List-related tools
│   │   ├── members.ts    # Member-related tools
│   │   ├── search.ts     # Search functionality
│   │   └── advanced.ts   # Advanced features
│   ├── trello/           # Trello API client
│   │   └── client.ts     # API client with retry logic
│   ├── types/            # TypeScript type definitions
│   └── utils/            # Utility functions
├── dist/                 # Compiled JavaScript
└── package.json          # Project configuration

从源码构建

# Install dependencies
npm install

# Build the project
npm run build

# Run type checking
npm run type-check

测试

该服务包含全面的错误处理和校验。通过以下方式测试你的设置：

1. 检查 MCP 客户端的连接状态
2. 运行一个简单命令，例如 "Show me my Trello boards"
3. 确认响应中包含你的看板数据

故障排查

常见问题

1. "No Trello tools available"

   • 确保配置后已完全重启 MCP 客户端
   • 检查配置中的路径是否指向 dist/index.js
   • 确认该文件存在且已构建

2. "Invalid credentials"

   • 仔细检查你的 API key 和 token
   • 确保 token 具有读/写权限
   • 如有需要，重新生成 token

3. "Rate limit exceeded"

   • 该服务包含自动重试逻辑
   • 如果触发限制，请等待几分钟
   • 考虑降低请求频率

调试日志

查看 MCP 客户端的日志以获取连接和错误详情。对于 Claude Desktop，日志位于：

• macOS：~/Library/Logs/Claude/mcp-server-trello.log
• Windows：%APPDATA%\Claude\Logs\mcp-server-trello.log

贡献

欢迎贡献！请：

1. Fork 仓库
2. 创建一个功能分支
3. 为新功能添加测试
4. 提交 pull request

许可证

MIT License - 详情请参阅 LICENSE 文件

致谢

• 使用 Model Context Protocol SDK 构建
• 使用 Trello REST API
• 兼容 Claude Desktop、Claude Code、Gemini CLI 及其他 MCP 客户端