内容
# trello-mcp
一个 [MCP](https://modelcontextprotocol.io) 服务器（stdio），允许像 Claude Code、Claude Desktop 或 Cursor 这样的 AI 客户端读取和**完全管理**一个 Trello 看板：创建看板、列表和卡片，移动卡片，管理检查清单、标签、评论、附件、自定义字段、成员、网络钩子等。
它公开了 **66 个工具**，涵盖了 Trello REST API 的全部功能，因此您可以从 AI 助手管理看板的 100% 功能。
## 功能
- **看板** — 列出、获取、创建、重命名、存档/重新打开、删除、设置偏好
- **列表** — 列出、获取、创建、重命名、存档/重新打开、移动、移动所有卡片
- **卡片** — 列出、获取、创建、更新、移动、复制、存档、删除、到期日期、封面
- **检查清单** — 创建、列出、重命名、删除、添加/检查/更新/删除项目
- **标签** — 列出、创建、更新、删除、添加/从卡片中移除
- **成员** — 列出看板成员、分配/取消分配、获取个人资料
- **评论** — 添加、列出、编辑、删除
- **附件** — 添加（URL）、列出、删除
- **贴纸** — 添加到卡片
- **自定义字段** — 列出、创建、删除、设置/获取值（自定义字段增强功能）
- **工作区** — 列出、获取、列出看板
- **网络钩子** — 列出、创建、删除
- **搜索** — 跨卡片和看板
## 要求
- Node.js 18+（用于内置 `fetch`）
- 一个 Trello 账户和 API 凭证（见下文）
## 安装
```bash
git clone https://github.com/irolon/trello-mcp.git
cd trello-mcp
npm install
npm run build
```
这将 TypeScript 源代码编译到 `build/` 目录。入口点是 `build/index.js`。
## 获取 Trello 凭证
您需要两个值：一个 **API 密钥** 和一个 **令牌**。
1. **API 密钥** — 登录 Trello 并前往 <https://trello.com/power-ups/admin>。创建一个 Power-Up（任意名称，选择您的工作区），打开它，并复制显示的 **API 密钥**。
2. **令牌** — 在同一页面上，点击 **令牌** 链接（或访问它显示的 `https://trello.com/1/authorize?...` URL），批准授权，并复制令牌字符串。
完整的逐步说明：[docs/CREDENTIALS.md](docs/CREDENTIALS.md)。
> 同时请保密这两个值。它们通过环境变量传递，并且此服务器从不记录它们。不要提交它们 — `.env` 被 gitignore。
## 配置
服务器读取两个环境变量：
| 变量 | 描述 |
| --- | --- |
| `TRELLO_API_KEY` | 您的 Trello API 密钥 |
| `TRELLO_TOKEN` | 您的 Trello 令牌 |
### Claude Code（CLI）
```bash
claude mcp add trello node /absolute/path/to/trello-mcp/build/index.js \
--env TRELLO_API_KEY=your-key \
--env TRELLO_TOKEN=your-token
```
然后重启 Claude Code 并运行 `/mcp` 以确认 `trello` 已连接。
### Claude Desktop / Cursor / 其他客户端
将以下内容添加到客户端的 MCP 配置中（例如 `claude_desktop_config.json`）：
```json
{
"mcpServers": {
"trello": {
"command": "node",
"args": ["/absolute/path/to/trello-mcp/build/index.js"],
"env": {
"TRELLO_API_KEY": "your-key",
"TRELLO_TOKEN": "your-token"
}
}
}
}
```
在 Windows 上，请使用类似 `C:/Users/you/trello-mcp/build/index.js` 的路径。
## 工具
所有 66 个工具，按区域分组：
| 区域 | 工具 |
| --- | --- |
| 看板 | `list_boards`、`get_board`、`create_board`、`update_board`、`close_board`、`reopen_board`、`delete_board`、`set_board_pref` |
| 列表 | `list_lists`、`get_list`、`create_list`、`update_list`、`archive_list`、`reopen_list`、`move_list`、`move_all_cards` |
| 卡片（读取） | `list_cards`、`get_card` |
| 卡片（写入） | `create_card`、`update_card`、`move_card`、`copy_card`、`archive_card`、`delete_card`、`set_due_complete`、`set_card_dates`、`set_card_cover` |
| 检查清单 | `add_checklist`、`list_checklists`、`rename_checklist`、`delete_checklist`、`add_checklist_item`、`set_checklist_item`、`update_checklist_item`、`delete_checklist_item` |
| 标签 | `list_labels`、`create_label`、`update_label`、`delete_label`、`add_label_to_card`、`remove_label_from_card` |
| 成员 | `list_board_members`、`assign_member`、`unassign_member`、`get_me`、`get_member` |
| 评论 | `add_comment`、`list_comments`、`update_comment`、`delete_comment` |
| 附件 | `add_attachment`、`list_attachments`、`delete_attachment` |
| 贴纸 | `add_sticker` |
| 自定义字段 | `list_custom_fields`、`create_custom_field`、`delete_custom_field`、`set_card_custom_field`、`get_card_custom_fields` |
| 工作区 | `list_workspaces`、`get_workspace`、`list_workspace_boards` |
| 网络钩子 | `list_webhooks`、`create_webhook`、`delete_webhook` |
| 搜索 | `search` |
### 示例提示
连接后，您可以向您的助手提出以下问题：
- “列出我的 Trello 看板。”
- “创建一个名为 *Sprint 12* 的看板，包含 To Do / Doing / Done 列表。”
- “在 To Do 列表中添加一个名为 'Fix login bug' 的卡片，并给它一个红色标签。”
- “将所有卡片从 Doing 移动到 Done。”
- “在卡片 X 上添加一个名为 'Release steps' 的检查清单，包含三个项目。”
## 开发
```bash
npm test # 运行 vitest 套件（无网络；fetch 被模拟）
npm run build # 将 TypeScript 编译到 build/
```
代码库组织如下：
- `src/config.ts` — 从环境中加载和验证凭证
- `src/trello-client.ts` — Trello REST API 的类型化包装器
- `src/tools/` — 每个工具组一个文件，每个文件定义 MCP 工具定义
- `src/server.ts` — 在 `McpServer` 上注册所有工具
- `src/index.ts` — stdio 入口点
测试涵盖每个客户端方法和每个工具的参数转发。`fetch` 被依赖注入，因此套件完全离线运行。
## 安全
- 凭证仅从环境变量读取，**从不记录**。
- 配置对象从不打印；只显示净化的错误消息。
- `.env`、`node_modules/` 和 `build/` 被 gitignore。
## 许可证
MIT
