内容
# MCP 工具
MCP（模型上下文协议）服务器，用 Python 实现，提供 Trello 操作作为 AI 代理（如 Claude Code、**OpenCode**、Claude Desktop、Cursor 等）的工具。
## ✨ 特点
- **🧠 智能模糊匹配** — AI 不需要知道确切的 ID 或名称。 "移动到当前冲刺" 可以与近似值匹配。
- **🛠️ 专注于软件工程** — 工具设计用于工程流程：按名称创建列表中的卡片、移动列表、评论。
- **Markdown-First** — 清洁的响应，无噪音。
## 工具列表
| 工具 | 描述 |
| ------------------- | --------------------------------------------------- |
| `create_card` | 在列表中创建卡片（按名称） |
| `move_card` | 在列表之间移动卡片 |
| `add_comment` | 在卡片上评论 |
| `list_cards` | 按列表分组列出所有卡片 |
| `board_status` | 摘要：按列表计算卡片数量 |
| `add_label` | 向卡片添加现有标签 |
| `create_checklist` | 在卡片上创建检查清单，带有可选项目 |
| `get_card_details` | 卡片的完整详细信息（描述、截止日期、标签、成员、检查清单） |
所有工具都接受可选的 `board_name` — 如果省略，则使用在 `TRELLO_BOARD_ID` 中配置的默认板。传递名称（使用模糊匹配，如列表/标签）使工具在同一令牌可访问的另一个板上运行。
## 安装
### 前置条件：uv
需要安装的唯一软件。 没有它，选项 A 的 `uvx` 命令就不存在。
```bash
curl -LsSf https://astral.sh/uv/install.sh | sh
```
（Windows：`powershell -c "irm https://astral.sh/uv/install.ps1 | iex"`。） 不需要单独安装 Python/pip — `uv` 会自行解决。
### 选项 A — uvx（推荐，不需要克隆任何内容）
运行交互式向导 — 它会解释如何获取 Trello API 密钥/令牌并将所有内容保存在 `~/.config/mcp-trello/.env` 中：
```bash
uvx --from git+https://github.com/vick1st/mcp-trello mcp-trello setup
```
完成 — 不需要其他手动安装步骤。 将您的 MCP 客户端指向以下命令（请参阅每个客户端的部分）。
### 选项 B — 本地克隆（贡献代码）
```bash
git clone https://github.com/vick1st/mcp-trello
cd mcp-trello
python3 -m venv .venv
source .venv/bin/activate # Linux/Mac
pip install -e .
mcp-trello setup # 与选项 A 相同的向导
```
### 验证
```bash
mcp-trello
```
如果登录 `TrelloClient initialized` 和 `MCP Trello Server starting...`，则表示正常（`Ctrl+C` 退出）。
以下客户端均使用 **相同的命令**，无需绝对路径，也无需克隆仓库：
```
command: uvx
args: ["--from", "git+https://github.com/vick1st/mcp-trello", "mcp-trello"]
```
凭证已保存在 `~/.config/mcp-trello/.env` 中（由 `mcp-trello setup` 完成），因此无需在每个客户端中重复密钥 — 除非您更喜欢按项目隔离（请参见下面的环境变量替代方案）。
## 在 OpenCode 中配置
`opencode.json`（项目根目录）或 `~/.config/opencode/mcp.json`（全局）：
```json
{
"mcpServers": {
"mcp-trello": {
"command": "uvx",
"args": ["--from", "git+https://github.com/vick1st/mcp-trello", "mcp-trello"]
}
}
}
```
或通过 CLI：
```bash
opencode mcp add mcp-trello -- uvx --from git+https://github.com/vick1st/mcp-trello mcp-trello
```
重启 OpenCode 会话 — 工具会自动出现。
## 在 Claude Code 中配置
`.mcp.json`（项目）或通过 CLI：
```json
{
"mcpServers": {
"mcp-trello": {
"command": "uvx",
"args": ["--from", "git+https://github.com/vick1st/mcp-trello", "mcp-trello"]
}
}
}
```
```bash
claude mcp add mcp-trello -- uvx --from git+https://github.com/vick1st/mcp-trello mcp-trello
```
## 在 Claude Desktop 中配置
最后一种情况 — 需要管理原生应用。 编辑 `~/.config/claude-desktop/claude_desktop_config.json`（Linux）或等效文件，并使用上述相同的 `command`/`args` 块。
## 替代方案：直接在客户端提供凭证（无需运行 `setup`）
如果您的 MCP 客户端支持每个服务器的 `env` 字段，则可以直接跳过向导并在配置中传递变量（适用于 CI 或多个板）：
```json
{
"mcpServers": {
"mcp-trello": {
"command": "uvx",
"args": ["--from", "git+https://github.com/vick1st/mcp-trello", "mcp-trello"],
"env": {
"TRELLO_API_KEY": "...",
"TRELLO_TOKEN": "...",
"TRELLO_BOARD_ID": "..."
}
}
}
}
```
**如何获取凭证：**
1. 访问 https://trello.com/power-ups/admin
2. 创建/打开您的 Power-Up → 复制 **API 密钥**
3. 通过在浏览器中打开以下网址生成令牌：`https://trello.com/1/authorize?expiration=never&scope=read,write&response_type=token&key=您的_API_密钥` → 授权 → 复制令牌
4. `TRELLO_BOARD_ID`：从板 URL 中获取， `https://trello.com/b/{BOARD_ID}/板名称`
## 故障排除
**`uvx: command not found`** — 安装 uv： `curl -LsSf https://astral.sh/uv/install.sh | sh`.
**调用任何工具时出现 `invalid key`** — 密钥重新生成或从旧门户复制。 在 https://trello.com/power-ups/admin 上确认。
**`invalid app token` / `token not found`** — 令牌复制错误。 不要将“秘密”（API 秘密）与“令牌”（通过授权 URL 生成）混淆。
**`LIST_NOT_FOUND` / `CARD_NOT_FOUND`** — 模糊匹配尝试近似匹配，截止值为 0.75。 如果失败，请使用 `list_cards` 查看确切名称。
**Claude/OpenCode 看不到工具** — 在编辑配置后完全重启会话。
## 结构
```
src/mcp_trello/
├── cli.py # 控制台脚本的入口点（服务器或 `setup`）
├── setup_wizard.py # 交互式凭证向导
├── server.py # MCP 协议，工具注册
├── trello/client.py # HTTP + 身份验证 + 与 Trello 的模糊匹配
├── tools/ # 异步处理程序，每个 MCP 工具一个
└── config/settings.py # 加载并验证凭证（环境变量 / .env）
```
