Trello

trellio-mcp — Trello 的 MCP 服务

一个 MCP 服务，让 Claude Desktop、Claude Code 和 Gemini CLI 能够全面访问 Trello API。基于 trellio 异步客户端 库和官方 Python MCP SDK 构建。遵循 BDD Guidelines v1.8.0 开发。

功能

• 48 个 MCP 工具 — 与 trellio 方法一一对应，另加 一个组合式 get_board_overview 工具
• 2 个资源模板 — trello://board/{id} 和 trello://card/{id}，用于加载丰富上下文
• 3 个提示词 — summarize_board、create_sprint、 daily_standup，作为工作流快捷方式
• 内置身份验证流程 — python -m trello_mcp auth 会打开 浏览器，用户点击“Allow”后，令牌将安全存储
• 结构化错误处理 — 将 Trello API 错误转换为清晰且可执行的 MCP 错误消息
• stdio 传输 — 作为本地子进程运行，不暴露网络接口

工具

类别	工具	数量
发现	list_boards、search	2
看板	get_board_overview、create_board、get_board、update_board、delete_board	5
列表	list_lists、create_list、update_list、archive_list	4
卡片	list_cards、create_card、get_card、update_card、archive_card、unarchive_card、delete_card、add_label_to_card、remove_label_from_card	9
标签	list_board_labels、create_label、update_label、delete_label	4
检查清单	list_card_checklists、create_checklist、delete_checklist、create_check_item、update_check_item、delete_check_item	6
评论	list_comments、add_comment、update_comment、delete_comment	4
成员	get_me、list_board_members、get_member	3
附件	list_attachments、create_attachment、get_attachment、upload_attachment、download_attachment、delete_attachment	6
Webhook	list_webhooks、create_webhook、get_webhook、update_webhook、delete_webhook	5

卡片工具在创建和更新时支持 pos（顶部/底部）、idLabels （逗号分隔）、due（ISO 8601）和 dueComplete （true/false）。

前提条件

• Python 3.10+
• 一个 Trello API Key （将 http://localhost:8095 添加到 Allowed Origins）

安装

使用 pipx（推荐）

全局安装后，trellio-mcp 命令即可在 PATH 中使用：

pipx install trellio-mcp

也可以按需运行，无需安装：

pipx run trellio-mcp

（注意：如果使用 pipx run，MCP 客户端配置也必须将 pipx 设为命令，并将 run trellio-mcp 设为参数。）

使用 pip

pip install trellio-mcp

从源代码安装

git clone https://github.com/scaratec/trellio-mcp.git
cd trellio-mcp
python3 -m venv .venv
.venv/bin/pip install -e ".[dev]"

身份验证

交互式（推荐）

在每台机器上运行身份验证命令，以连接你的 Trello 账户：

如果已全局安装（pipx install 或 pip install）：

TRELLO_API_KEY=your_api_key trellio-mcp auth

如果按需运行（pipx run）：

TRELLO_API_KEY=your_api_key pipx run trellio-mcp auth

这会打开浏览器，你可以在其中授权此应用。令牌 会自动获取并存储在 ~/.config/trellio-mcp/credentials.json 中（权限为 0600）。

完成身份验证后，无需设置环境变量 — 服务 启动时会读取已存储的凭据。

环境变量（备用方式）

如果没有找到已存储的凭据，服务会改用 环境变量：

export TRELLO_API_KEY=your_api_key
export TRELLO_TOKEN=your_token

MCP 客户端配置

Claude Desktop

添加到 ~/Library/Application Support/Claude/claude_desktop_config.json （macOS）或 %APPDATA%\Claude\claude_desktop_config.json （Windows）：

{
  "mcpServers": {
    "trello": {
      "command": "pipx",
      "args": ["run", "trellio-mcp"]
    }
  }
}

如果使用环境变量身份验证而非已存储的凭据，请添加：

"env": {
  "TRELLO_API_KEY": "your_api_key",
  "TRELLO_TOKEN": "your_token"
}

Claude Code

添加到 ~/.claude/settings.json 或项目中的 .claude/settings.json：

{
  "mcpServers": {
    "trello": {
      "command": "pipx",
      "args": ["run", "trellio-mcp"]
    }
  }
}

Gemini CLI

添加到 ~/.gemini/settings.json：

{
  "mcpServers": {
    "trello": {
      "command": "pipx",
      "args": ["run", "trellio-mcp"]
    }
  }
}

架构

MCP Client (Claude / Gemini)
    │ stdio (JSON-RPC)
    ▼
trellio-mcp (FastMCP)
    │ async/await
    ▼
trellio (httpx)
    │ HTTPS
    ▼
Trello API

关键决策（记录在 docs/adr/ 中）：

ADR	决策
001	使用 Python MCP SDK，与 trellio 的语言保持一致
002	使用 stdio 传输——无网络攻击面
003	使用已存储的凭据，并在必要时回退到环境变量
004	工具一一映射——每个 trellio 方法对应一个工具
005	将 trellio 作为 PyPI 依赖项（>=1.4.0）
006	将工具、资源和提示词作为 MCP 能力
007	使用 isError=true + 结构化错误内容

已接受的弱点单独记录在 docs/limitations/ 中。此处列出的限制已与更完善的解决方案进行权衡，但最终未予采纳——在为已知的不完美行为提出修复方案前，请先查看该清单。

测试

本项目采用 BDD，使用 behave，并遵循 BDD 指南 v1.8.0。

PYTHONPATH=src .venv/bin/python -m behave

18 features passed, 0 failed, 0 skipped
182 scenarios passed, 0 failed, 0 skipped
1103 steps passed, 0 failed, 0 skipped

dependency_compatibility.feature 需要网络访问：它会构建一个 wheel，将其安装到声明的 mcp 版本范围两端的临时环境中，并通过 stdio 驱动生成的服务。只有这个功能能检测出有问题的依赖声明——其他功能都是针对本地 .venv 导入工具函数。它有意不带任何选择加入标签：必须主动请求才会运行的依赖防护称不上防护。若要离线运行测试套件，请显式排除它：

PYTHONPATH=src .venv/bin/python -m behave \
  --exclude dependency_compatibility

测试架构：

• AsyncMock(spec=TrellioClient)——在客户端边界进行模拟，而非 HTTP
• 通过模拟调用记录验证持久化（§4.3）
• 通过至少包含 2 个变体的场景大纲防止硬编码（§2.3）
• 按层枚举失败路径（§4.5）
• 根据 §13 进行独立规范审查

请参阅案例研究，详细了解 BDD 驱动的开发流程。

项目结构

trellio-mcp/
├── src/trello_mcp/
│   ├── __init__.py        # Tool registration
│   ├── __main__.py        # Entry point (server + auth)
│   ├── server.py          # FastMCP instance + client mgmt
│   ├── auth.py            # OAuth flow + credential storage
│   ├── errors.py          # Error translation (ADR 007)
│   ├── tools/             # 10 modules, 48 tools
│   ├── resources.py       # 2 resource templates
│   └── prompts.py         # 3 prompts
├── features/              # 18 BDD feature files
│   └── steps/             # Step definitions
├── docs/
│   ├── adr/               # 7 Architecture Decision Records
│   ├── limitations/       # Limitation Records (accepted weaknesses)
│   ├── tool-design.md     # Scenario-driven tool analysis
│   └── case-study-bdd-mcp-server.md
└── pyproject.toml

发布

PyPI

uv build
twine upload dist/trellio_mcp-<version>*

Smithery

命名空间为 gupta。发布新的 PyPI 版本后，请更新发布版本：

npx @smithery/cli mcp publish "https://github.com/scaratec/trellio-mcp" -n gupta/trellio-mcp

还要更新 smithery.yaml commandFunction 中固定的版本。

生成的列表仍会为空。 Smithery 会通过 HTTP 扫描服务来填充外部条目；本服务仅支持 stdio（ADR 002），因此扫描会失败，条目不会包含连接信息或工具列表——即使发布命令报告成功也是如此。请参阅 LIM 0001。 请改用 pipx 或 uvx 安装。

MCP 注册表

server.json 通过静态声明而非自省来描述面向官方 MCP 注册表的服务。请确保其中两个 version 字段与 pyproject.toml 中的版本一致。

许可证

本项目采用 GNU 通用公共许可证 v3.0 授权——详情请参阅 LICENSE 文件。