MCP 服务器 Trello 版

smithery 徽章

这是一个基于模型上下文协议（MCP）的服务器，提供与 Trello 看板交互的工具。该服务器能够无缝集成 Trello 的 API，同时自动处理速率限制、类型安全和错误处理。

更新日志

0.3.0 版本

新增看板和空间管理功能：
- list_boards - 列出用户可访问的所有看板
- set_active_board - 设置未来操作的活跃看板
- list_workspaces - 列出用户可访问的所有空间
- set_active_workspace - 设置未来操作的活跃空间
- list_boards_in_workspace - 列出特定空间中的所有看板
- get_active_board_info - 获取当前活跃看板的信息
新增持久化配置存储，记住活跃看板/空间
改进所有新操作的错误处理

0.2.1 版本

为速率限制器函数添加详细的 JSDoc 注释
改进图片附件功能的错误处理
更新 attach_image_to_card 工具的文档

0.2.0 版本

新增 attach_image_to_card 工具，支持通过 URL 将图片附加到卡片
添加 Docker 支持，采用多阶段构建
通过将环境变量移至 .env 文件提升安全性
添加 Docker Compose 配置
新增 .env.template 文件便于设置

0.1.1 版本

新增 move_card 工具，支持在列表间移动卡片
改进文档

0.1.0 版本

初始发布，包含基本的 Trello 看板管理功能

功能特点

完整的 Trello 看板集成：可交互卡片、列表和看板活动
内置速率限制：遵守 Trello API 限制（每个 API 密钥每 10 秒 300 次请求，每个令牌每 10 秒 100 次请求）
类型安全实现：使用 TypeScript 编写，包含全面的类型定义
输入验证：对所有 API 输入进行严格验证
错误处理：提供带有详细信息的优雅错误处理
动态看板选择：无需重启即可切换看板和空间

安装方式

Docker 安装（推荐）

运行服务器最简单的方式是使用 Docker：

克隆仓库：

git clone https://github.com/delorenj/mcp-server-trello
cd mcp-server-trello

复制环境模板并填写您的 Trello 凭据：

cp .env.template .env

使用 Docker Compose 构建并运行：

docker compose up --build

通过 Smithery 安装

要通过 Smithery为 Claude Desktop 自动安装 Trello 服务器：

npx -y @smithery/cli install @modelcontextprotocol/mcp-server-trello --client claude

手动安装

npm install @delorenj/mcp-server-trello

配置说明

环境变量

服务器可通过环境变量进行配置。在根目录创建 .env 文件并设置以下变量：

# 必填：您的 Trello API 凭据
TRELLO_API_KEY=您的API密钥
TRELLO_TOKEN=您的令牌

# 必填：初始看板 ID（稍后可通过 set_active_board 更改）
TRELLO_BOARD_ID=您的看板ID

# 可选：初始空间 ID（稍后可通过 set_active_workspace 更改）
TRELLO_WORKSPACE_ID=您的空间ID

您可以从以下位置获取这些值：

API 密钥：https://trello.com/app-key
令牌：使用您的 API 密钥生成
看板 ID：位于看板 URL 中（例如 https://trello.com/b/BOARD_ID/看板名称）
空间 ID：位于空间设置中或通过 list_workspaces 工具获取

看板和空间管理

从 0.3.0 版本开始，MCP 服务器支持动态选择看板和空间：

您的 .env 文件中的 TRELLO_BOARD_ID 用作服务器启动时的初始看板 ID
您可以随时使用 set_active_board 工具更改活跃看板
所选看板会在服务器重启后保留（存储在 ~/.trello-mcp/config.json 中）
同样，您可以使用 set_active_workspace 设置并保留活跃空间

这使您可以在不重启服务器或更改环境变量的情况下使用多个看板和空间。

示例工作流程

首先列出可用看板：

{
  name: 'list_boards',
  arguments: {}
}

设置您的活跃看板：

{
  name: 'set_active_board',
  arguments: {
    boardId: "abc123"  // 来自 list_boards 响应的 ID
  }
}

如有需要列出空间：

{
  name: 'list_workspaces',
  arguments: {}
}

如有需要设置活跃空间：

{
  name: 'set_active_workspace',
  arguments: {
    workspaceId: "xyz789"  // 来自 list_workspaces 响应的 ID
  }
}

检查当前活跃看板信息：

{
  name: 'get_active_board_info',
  arguments: {}
}

可用工具

get_cards_by_list_id

从特定列表获取所有卡片。

{
  name: 'get_cards_by_list_id',
  arguments: {
    listId: string  // Trello 列表的 ID
  }
}

get_lists

获取当前活跃看板中的所有列表。

{
  name: 'get_lists',
  arguments: {}
}

get_recent_activity

获取当前活跃看板的最近活动。

{
  name: 'get_recent_activity',
  arguments: {
    limit?: number  // 可选：要获取的活动数量（默认：10）
  }
}

add_card_to_list

向指定列表添加新卡片。

{
  name: 'add_card_to_list',
  arguments: {
    listId: string,       // 要添加卡片的列表 ID
    name: string,         // 卡片名称
    description?: string, // 可选：卡片描述
    dueDate?: string,    // 可选：到期日期（ISO 8601 格式）
    labels?: string[]    // 可选：标签 ID 数组
  }
}

update_card_details

更新现有卡片的详细信息。

{
  name: 'update_card_details',
  arguments: {
    cardId: string,       // 要更新的卡片 ID
    name?: string,        // 可选：卡片的新名称
    description?: string, // 可选：新描述
    dueDate?: string,    // 可选：新到期日期（ISO 8601 格式）
    labels?: string[]    // 可选：新的标签 ID 数组
  }
}

archive_card

将卡片归档。

{
  name: 'archive_card',
  arguments: {
    cardId: string  // 要归档的卡片 ID
  }
}

add_list_to_board

向当前活跃看板添加新列表。

{
  name: 'add_list_to_board',
  arguments: {
    name: string  // 新列表的名称
  }
}

archive_list

将列表归档。

{
  name: 'archive_list',
  arguments: {
    listId: string  // 要归档的列表 ID
  }
}

get_my_cards

获取分配给当前用户的所有卡片。

{
  name: 'get_my_cards',
  arguments: {}
}

move_card

将卡片移动到不同的列表。

{
  name: 'move_card',
  arguments: {
    cardId: string,  // 要移动的卡片 ID
    listId: string   // 目标列表的 ID
  }
}

attach_image_to_card

直接从 URL 将图片附加到卡片。

{
  name: 'attach_image_to_card',
  arguments: {
    cardId: string,  // 要附加图片的卡片 ID
    imageUrl: string, // 要附加的图片 URL
    name?: string    // 可选：附件的名称（默认为"图片附件"）
  }
}

list_boards

列出用户可访问的所有看板。

{
  name: 'list_boards',
  arguments: {}
}

set_active_board

设置未来操作的活跃看板。

{
  name: 'set_active_board',
  arguments: {
    boardId: string  // 要设置为活跃的看板 ID
  }
}

list_workspaces

列出用户可访问的所有空间。

{
  name: 'list_workspaces',
  arguments: {}
}

set_active_workspace

设置未来操作的活跃空间。

{
  name: 'set_active_workspace',
  arguments: {
    workspaceId: string  // 要设置为活跃的空间 ID
  }
}

list_boards_in_workspace

列出特定空间中的所有看板。

{
  name: 'list_boards_in_workspace',
  arguments: {
    workspaceId: string  // 要列出看板的空间 ID
  }
}

get_active_board_info

获取当前活跃看板的信息。

{
  name: 'get_active_board_info',
  arguments: {}
}

速率限制

服务器实现了令牌桶算法进行速率限制，以符合 Trello 的 API 限制：

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

速率限制会自动处理，如果达到限制，请求将被排队。

错误处理

服务器为各种情况提供详细的错误消息：

无效的输入参数
超过速率限制
API 认证错误
网络问题
无效的看板/列表/卡片 ID

开发指南

前提条件

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

设置步骤

克隆仓库

git clone https://github.com/delorenj/mcp-server-trello
cd mcp-server-trello

安装依赖

npm install

构建项目

npm run build

运行评估

evals 包会加载一个 mcp 客户端来运行 index.ts 文件，因此测试之间不需要重新构建。您可以通过在 npx 命令前添加前缀来加载环境变量。完整文档请参阅这里。

OPENAI_API_KEY=您的密钥  npx mcp-eval src/evals/evals.ts src/index.ts

贡献指南

欢迎贡献！

许可证

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

致谢

使用 Model Context Protocol SDK 构建
使用 Trello REST API