trello-mcp-server

🚀 Trello MCP 服务：AI 驱动的项目管理

将你的 Trello 看板转变为 AI Agent 的动态工作空间。此 Model Context Protocol（MCP） 服务允许大模型（如 Gemini、Claude 和 GPT-4）通过自然语言查看、整理和管理项目。

---

🔍 概览

此项目弥合了 AI 与 Trello 工作流之间的差距。你无需手动移动卡片，只需告诉 AI：“将所有带有 ‘Urgent’ 标签的 ‘To Do’ 卡片移至 ‘In Progress’，并分配给我。”

**全局使用：**你可以将此项目保存在计算机上的任意位置。完成注册后，AI 会在需要时自动启动服务，无需手动在终端中执行。

---

📋 前置条件

• Node.js（建议使用 v20.0.0 或更高版本）- 在此下载
• Git - 在此下载
• Trello API Key 和 Token：在此获取

---

🛠️ 快速开始

1. 安装与构建

# Clone the repository
git clone https://github.com/BillNobill/trello-mcp-server.git

# Install dependencies and build
npm install
npm run build

2. 配置

在项目根目录中创建 .env 文件（使用 .env.example 作为模板）：

TRELLO_API_KEY=your_api_key
TRELLO_TOKEN=your_token
TRELLO_BASE_URL=https://api.trello.com/1

3. 在 AI 客户端中注册

Claude Code（推荐）

claude mcp add --scope user trello node "C:\FULL_PATH\TO\trello-mcp-server\dist\index.js"

环境变量会从 .env 文件中读取，也可以通过 -e KEY=VALUE 标志以内联方式传入。

VS Code（GitHub Copilot / Claude 扩展）

将以下内容添加到用户的 settings.json 中（Ctrl+Shift+P → 打开用户设置 JSON）：

{
  "mcp": {
    "servers": {
      "trello": {
        "command": "node",
        "args": ["C:\\FULL_PATH\\TO\\trello-mcp-server\\dist\\index.js"],
        "env": {
          "TRELLO_API_KEY": "your_api_key",
          "TRELLO_TOKEN": "your_token",
          "TRELLO_BASE_URL": "https://api.trello.com/1"
        }
      }
    }
  }
}

Cursor

添加到 %USERPROFILE%\.cursor\mcp.json：

{
  "mcpServers": {
    "trello": {
      "command": "node",
      "args": ["C:\\FULL_PATH\\TO\\trello-mcp-server\\dist\\index.js"],
      "env": {
        "TRELLO_API_KEY": "your_api_key",
        "TRELLO_TOKEN": "your_token",
        "TRELLO_BASE_URL": "https://api.trello.com/1"
      }
    }
  }
}

重要

请务必在上述配置中使用 dist/index.js 的绝对路径。

---

⚡ 可用工具

你的 AI Agent 会自动“学会”以下高级功能：

📋 看板与列表管理

• list_boards：列出所有 Trello 看板。
• read_board：深入查看列表、卡片、标签和成员。
• get_lists_on_board：仅获取列名称和 ID。
• create_list / update_list：管理看板列及其顺序（pos）。
• archive_list：整理看板结构。
• get_board_labels / get_board_members：获取 ID，以便进行精准自动化。
• create_label / update_label：管理看板标签（名称和颜色）。

🗂️ 卡片操作（精细且高效）

• get_cards_in_list：获取指定列中的卡片。
• get_card_details：深入查看单张卡片的评论、附件和检查清单。
• search_cards：在整个看板中进行快速文本搜索。
• create_card / update_card：创建或修改任务（名称、描述、日期、标签和 pos）。
• move_card：在不同列表间更改任务状态（支持 pos）。
• move_all_cards：将一个列表中的所有卡片移至另一个列表的批量操作。
• archive_card：整理已完成的工作。

✅ 检查清单管理（精细且灵活）

• add_checklist：在卡片上创建新的检查清单标题。
• update_checklist：重命名或重新排序现有检查清单标题。
• delete_checklist：彻底删除检查清单。
• create_checkitem：向现有检查清单添加新项目。
• update_checkitem：更新项目（重命名、标记为已完成/未完成，或重新排序）。
• delete_checkitem：从检查清单中删除指定项目。

📁 文件与附件

• add_attachment：将基于 URL 的链接附加到卡片。
• upload_file：直接从计算机向卡片上传真实文件（PDF、脚本、报告）。

🛠️ 专业功能

• set_custom_field：为自定义字段设置值（例如“估算”“项目 ID”）。注意：需要在看板上启用 Custom Fields Power-Up。
• assign_member：将队友分配给任务。
• add_comment：直接通过 AI 讨论任务。

提示

重新排序（pos 参数）：
使用 'top'、'bottom' 或正数（例如 1），即可精确调整卡片、列表、检查清单和项目的顺序。

---

🛠️ 故障排查

警告

服务显示为“已断开连接”？

1. 命令为空： 检查客户端的 MCP 配置，并确认 "command": "node" 和 dist/index.js 的绝对路径正确。
2. 环境变量： 在终端中手动运行 node dist/index.js。如果运行失败，可能是根目录中缺少 .env。
3. SDK 兼容性： 此项目使用 @modelcontextprotocol/sdk v1.29.0。如果遇到协议错误，请运行 npm install，确保安装了正确的版本。
4. Claude Code： 在 Claude Code 会话中运行 /mcp，查看服务状态和任何错误输出。

---

🐳 Docker 支持

提示

Docker 非常适合保持本地环境整洁。

# Build
docker build -t trello-mcp-server .

# Run
docker run --rm -i --env-file .env trello-mcp-server

---

🤝 参与贡献

欢迎贡献！如果你发现了错误或有功能需求，请提交 issue 或拉取请求。

---

由 [Luiz Feltrin] 创建
表达你的支持！如果这个仓库对你有帮助，请点亮 ⭐️！