Claude MCP Trello

Claude MCP Trello

一个 Model Context Protocol（MCP）服务，提供用于与 Trello 看板交互的工具。该服务可与 Trello API 无缝集成，并自动处理速率限制、类型安全和错误处理。

功能

• 全面集成 Trello 看板：与卡片、列表和看板活动交互
• 内置速率限制：遵守 Trello API 限制（每个 API 密钥每 10 秒 300 个请求，每个令牌每 10 秒 100 个请求）
• 类型安全的实现：使用 TypeScript 编写，并提供全面的类型定义
• 输入验证：对所有 API 输入进行可靠验证
• 错误处理：提供清晰的错误信息，并妥善处理错误

可用工具

trello_get_cards_by_list

获取指定列表 ID 中的卡片列表。

{
  name: "trello_get_cards_by_list",
  arguments: {
    listId: string; // Trello list ID
  }
}

trello_get_lists

获取指定看板中的所有列表。

{
  name: "trello_get_lists",
  arguments: {
    boardId: string; // The ID of the Trello board to get lists from
  }
}

trello_get_recent_activity

获取指定看板的最新活动。limit 参数可指定获取数量（默认值：10）。

{
  name: "trello_get_recent_activity",
  arguments: {
    boardId: string; // The ID of the Trello board to get activity from
    limit?: number;  // Optional: number of activities to retrieve
  }
}

trello_add_card

向指定列表添加卡片。

{
  name: "trello_add_card",
  arguments: {
    listId: string;       // The ID of the list to add to
    name: string;         // The title of the card
    description?: string; // Optional: details of the card
    dueDate?: string;     // Optional: due date (e.g., ISO8601)
    labels?: string[];    // Optional: array of label IDs
  }
}

trello_update_card

更新卡片内容。

{
  name: "trello_update_card",
  arguments: {
    cardId: string;       // The ID of the card to be updated
    name?: string;        // Optional: updated title
    description?: string; // Optional: updated description
    dueDate?: string;     // Optional: updated due date (e.g., ISO8601)
    labels?: string[];    // Optional: updated array of label IDs
  }
}

trello_archive_card

归档（关闭）指定卡片。

{
  name: "trello_archive_card",
  arguments: {
    cardId: string; // The ID of the card to archive
  }
}

trello_add_list

向指定看板添加新列表。

{
  name: "trello_add_list",
  arguments: {
    boardId: string; // The ID of the Trello board to add the list to
    name: string;    // Name of the new list
  }
}

trello_archive_list

归档（关闭）指定列表。

{
  name: "trello_archive_list",
  arguments: {
    listId: string; // The ID of the list to archive
  }
}

trello_get_my_cards

获取与你的账户相关的所有卡片。

{
  name: "trello_get_my_cards",
  arguments: {}
}

trello_search_all_boards

根据套餐和权限，在工作区（组织）的所有看板中执行跨看板搜索。

{
  name: "trello_search_all_boards",
  arguments: {
    query: string;   // Search keyword
    limit?: number;  // Optional: max number of results (default: 10)
  }
}

trello_get_card_attachments

获取指定卡片的所有附件。返回附件元数据，包括名称、文件大小、MIME 类型和 URL。可先用此工具查看卡片上的附件，再下载附件。

{
  name: "trello_get_card_attachments",
  arguments: {
    cardId: string;  // The ID of the Trello card to get attachments from
  }
}

返回包含以下属性的附件对象数组：

• id：附件的唯一标识符
• name：附件的显示名称
• url：访问或下载附件的 URL
• bytes：附件大小（以字节为单位；外部链接为 0）
• mimeType：MIME 类型（例如，“image/png”、“application/pdf”）
• date：添加附件时的 ISO 8601 日期字符串
• isUpload：是否为 Trello 上传的文件（true）或外部链接（false）
• fileName：附件的文件名

trello_download_attachment

从 Trello 卡片下载指定附件。对于直接上传到 Trello 的文件，以 Base64 编码数据的形式返回内容；对于外部链接，则返回 URL。

{
  name: "trello_download_attachment",
  arguments: {
    cardId: string;       // The ID of the Trello card containing the attachment
    attachmentId: string; // The ID of the attachment to download
  }
}

返回包含以下内容的对象：

• attachment：完整的附件元数据
• content：Base64 编码的文件内容（适用于 Trello 上传的文件）；外部链接则为 null
• url：附件的直接 URL

使用提示：先使用 trello_get_card_attachments 列出所有附件并获取其 ID，再使用 trello_download_attachment 下载指定文件。

速率限制

该服务使用令牌桶算法实施速率限制，以遵守 Trello API 限制：

• 每个 API 密钥每 10 秒 300 个请求
• 每个令牌每 10 秒 100 个请求

速率限制会自动处理；达到限制时，请求将进入队列。

错误处理

该服务会针对以下情况提供详细的错误信息：

• 输入参数无效
• 超出速率限制
• API 身份验证错误
• 网络问题
• 看板、列表或卡片 ID 无效

开发

前置条件

• Node.js 16 或更高版本
• npm 或 yarn

设置

1. 克隆仓库：

   git clone https://github.com/hrs-asano/claude-mcp-trello.git
   cd claude-mcp-trello
   

2. 安装依赖：

npm install

3. 构建项目：

npm run build

运行测试

npm test

与 Claude Desktop 集成

要将此 MCP 服务与 Claude Desktop 集成，请将以下配置添加到 ~/Library/Application\ Support/Claude/claude_desktop_config.json 文件中：

{
  "mcpServers": {
    "trello": {
      "command": "{YOUR_NODE_PATH}", // for example: /opt/homebrew/bin/node
      "args": [
        "{YOUR_PATH}/claude-mcp-trello/build/index.js"
      ],
      "env": {
        "TRELLO_API_KEY": "{YOUR_KEY}",
        "TRELLO_TOKEN": "{YOUR_TOKEN}"
      }
    }
  }
}

请务必将 {YOUR_NODE_PATH}、{YOUR_PATH}、{YOUR_KEY} 和 {YOUR_TOKEN} 替换为适合你环境的值。

注意： 看板 ID 作为参数传递给各个工具，而不是全局配置，因此你可以使用多个看板。

贡献

欢迎贡献！请阅读我们的贡献指南，了解行为准则以及提交拉取请求的流程。

许可证

本项目采用 MIT 许可证，详情请参阅 LICENSE 文件。

致谢

• 基于 Model Context Protocol SDK 构建
• 使用 Trello REST API