Trello MCP

将 Claude（桌面版/协作版 和 Claude Code）连接到 Trello 看板。

看板由配置中的 board_id 选择——没有硬编码任何特定看板的信息。

~/mcp-servers/trello-mcp/
    trello_mcp.py     the server — no credentials inside, safe to share
    requirements.txt  mcp==1.27.2 (pinned, see below)
    .venv/            dedicated Python 3.12 environment
~/.config/trello-mcp/config.json   credentials (chmod 600, never shared)

已在 两者 中注册：

• ~/Library/Application Support/Claude/claude_desktop_config.json（桌面版/协作版）

• ~/.claude.json（Claude Code）

两者都指向 绝对路径 的虚拟环境解释器。这一点至关重要——见下文。

为什么它以前每天早上都会断开连接

旧配置使用裸命令 python3 启动服务器。这台 Mac 上有四个 python3 二进制文件，只有一个安装了 mcp 包：

python3 具体指向哪个取决于启动应用程序的进程的 PATH。从 Finder 或登录时 启动，应用程序继承最小的 launchd PATH（/usr/bin:/bin:/usr/sbin:/sbin），得到 Python 3.9 → ModuleNotFoundError: No module named 'mcp' → “无法连接 Trello MCP。” 从 终端 启动，它继承 shell 的 PATH，其中 Anaconda 排在前面 → 正常工作。因此：大多数早上都坏了，手动测试时却正常。

重现旧故障和修复方法：

env -i PATH=/usr/bin:/bin:/usr/sbin:/sbin python3 "$HOME/Claude/Projects/Daily Trello/trello_mcp.py"   # ModuleNotFoundError
env -i PATH=/usr/bin:/bin:/usr/sbin:/sbin ~/mcp-servers/trello-mcp/.venv/bin/python3 -c "import mcp; print('ok')"  # ok

使用绝对路径指定解释器意味着 完全不进行 PATH 查找。应用程序启动一个已知的二进制文件，该文件找到一个已知的包目录。早上 7 点和晚上 7 点结果相同。

Related MCP server: trello-mcp-server

虚拟环境到底是什么（以及它 不能 防止什么）

Python 在特定运行解释器所绑定的目录中查找已安装的包。四个解释器 = 四个独立的包目录；mcp 只安装到了其中一个。虚拟环境创建一个私有的目录，仅属于此服务器。

技术上：python3 -m venv .venv 创建 .venv/bin/python3 和一个记录基础安装的 pyvenv.cfg。启动时，解释器读取该文件并将 sys.prefix 设置为虚拟环境，因此 import 解析到 .venv/lib/python3.12/site-packages。

诚实的限制： 在 macOS 上，venv 符号链接 解释器而不是复制它，标准库仍然从基础安装加载：

.venv/bin/python3 -> /opt/anaconda3/bin/python3
stdlib             = /opt/anaconda3/lib/python3.12

因此，此虚拟环境 仍然依赖于已安装的 Anaconda。它隔离的是 包，而不是解释器。

在上述任何情况后重建，约 15 秒：

cd ~/mcp-servers/trello-mcp && rm -rf .venv
/path/to/any/python3.10+ -m venv .venv && ./.venv/bin/pip install -r requirements.txt

如果你想要真正独立于 Anaconda，请安装 uv 并从 uv 管理的独立 Python 构建虚拟环境。这里没有这样做，因为会给机器增加一个新工具。

不要盲目升级 mcp

requirements.txt 固定了 mcp==1.27.2。这是故意的：mcp 2.0.0 移除了此服务器所依赖的 @app.list_tools() / @app.call_tool() 装饰器 API。安装最新版本会立即破坏服务器，出现 AttributeError: 'Server' object has no attribute 'list_tools'——这看起来与整个设置旨在修复的连接失败完全一样。只有在同时重写新 API 的处理程序时才升级。

凭据文件的工作原理

~/.config/trello-mcp/config.json：

{ "api_key": "...", "token": "...", "board_id": "676f0bfc11723d27f716291d" }

没有托管，没有外部服务——只是一个在此磁盘上的普通 JSON 文件。两件事使其“秘密”：

1. 它位于 代码之外，因此复制或发布 trello_mcp.py 不会携带凭据。

2. chmod 600——只有此 macOS 用户帐户可以读取它。

服务器在启动时读取它并将值保存在内存中。要共享服务器，发送 trello_mcp.py；接收者使用自己的 Trello 密钥创建自己的配置。这个值不是加密——而是 将你分享的东西与你不想分享的东西分开。

Trello 令牌 没有过期时间（dateExpires: null），作用域为成员/看板/组织读写。与 Google Drive 服务器的 OAuth 刷新令牌不同，它不需要定期重新授权。

列表从不硬编码

每个列表在调用时通过 名称 从实时 API 解析，因此在 Trello 中添加的列表（每季度一个新班级）立即可用——无需更改代码，无需重启。一个 60 秒的缓存使其保持廉价；缓存未命中会在报告“未找到”之前强制重新获取一次，因此几秒前创建的列表仍然可以解析。

在此看板上测量：一次列表获取约 307 毫秒。没有缓存，每个工具调用都会支付这个代价（get_cards 需要两次往返），因此一个 12 张卡片的规划会议仅在重新获取上就消耗了约 3.7 秒。有了缓存，一次获取覆盖整个突发。

代码中 唯一 的列表名称是 trello_mcp.py 顶部的三个工作流锚点：

LIST_TODO    = "To Do Today"
LIST_WORKING = "Working on"
LIST_DONE    = "Done Today"

它们被命名是因为日常工作流程是根据它们定义的（sort_todo_today 不能被告知“排序表示今天的列表”而没有名称）。在 Trello 中重命名一个 → 在该块和 Daily Trello CLAUDE.md 中更改它。rename_list 会在你重命名锚点时发出警告。

工具（37 个）

读取 — get_all_lists、get_cards（包括附件、标签、截止日期、位置）、get_card（完整详情）、search_cards、get_board_summary

卡片 — create_card（带附件/标签/位置）、update_card、move_card、complete_card、archive_card、unarchive_card、copy_card、set_card_position、set_card_cover、sort_todo_today

附件 — get_attachments、add_attachment（URL 或 上传本地文件）、view_attachment（返回可查看的图像——这是 Claude 读取卡片上截图的方式）、delete_attachment

标签 — get_labels、add_label_to_card、remove_label_from_card、create_label

评论 — get_comments、add_comment

列表 — create_list、rename_list、archive_list、move_list

检查清单 — get_checklists、create_checklist、add_checklist_item、complete_checklist_item、uncheck_checklist_item、rename_checklist_item、delete_checklist_item、delete_checklist

已知看板设置：评论已禁用

add_comment 返回 401，因为 看板本身 关闭了评论功能（prefs.comments: "disabled"）——不是令牌或代码问题。要启用：Trello → 看板菜单 (···) → 设置 → 评论权限 → 看板成员。该工具会检测到这一点并解释，而不是显示原始 401。

关于 search_cards 的说明

Trello 的搜索索引有几秒延迟。刚刚创建的卡片可能不会立即出现；请改用其列表上的 get_cards。

故障排除

# 1. Does the interpreter still work?
~/mcp-servers/trello-mcp/.venv/bin/python3 -c "import mcp; print('ok')"

# 2. Does the server start and reach Trello? (Ctrl-C to exit; silence = healthy)
~/mcp-servers/trello-mcp/.venv/bin/python3 ~/mcp-servers/trello-mcp/trello_mcp.py

# 3. Are the configs still pointing at the venv?
grep -A3 '"trello"' ~/.claude.json "$HOME/Library/Application Support/Claude/claude_desktop_config.json"

更改任一配置后，完全退出并重新打开 应用程序——MCP 服务器仅在启动时启动。

此脚本的旧副本仍位于 ~/Claude/Projects/Daily Trello/trello_mcp.py 和 ~/Downloads/trello_mcp.py。没有指向它们；它们仍然包含嵌入的凭据，因此不要共享这两个文件。

用于简历/作品集

保留在这里，以便未来的简历会话有真实的版本，而不是重新构建。

值得讲述的故事 是失败，而不是功能。这个服务器连续几周每天早上都失败，但每次手动测试时都正常工作——这正是整个诊断：代码没问题，而 环境 有问题。配置命名为 python3；登录时启动的应用程序继承最小的 PATH（/usr/bin:/bin:/usr/sbin:/sbin），其中该命令解析为没有所需包的系统 Python，而终端继承的 PATH 中它正确解析。从 shell 测试是唯一保证通过的情况。

我实际做的： 指导调试。我的决定是——将“我测试时它工作”视为关于测试的证据，而不是对代码的安慰，并要求一个能重现真实启动条件（剥离的 PATH）的测试，而不是方便的测试。

结果，现在应用于每个集成：配置中的绝对解释器路径、每个项目专用环境、每个依赖项固定，以及一个检查每个已知故障模式并尽可能修复的诊断脚本。

作品集长度的要点：

指导了三个将 macOS 连接到云服务的自动化集成的开发，这些集成在计划任务上无人值守运行。将反复出现的每日故障根因定位到 shell 和应用程序启动上下文之间的 PATH 解析差异，并建立了绝对路径和固定依赖项约定，在所有三个集成中消除了该问题。

完整案例研究：https://zeno-blade-creator.github.io/projects/personal-integrations.html