trello-mcp

trello-mcp

一个可自托管的 Model Context Protocol 服务，让兼容 MCP 的客户端能够使用 Trello 卡片、列表、标签、附件、检查清单、成员和卡片活动。

本项目旨在支持自托管和重复使用。欢迎贡献、改编，以及针对性的问题报告。

路线图当然也在 Trello 上跟踪，而 trello-mcp 有助于保持路线图更新：trello-mcp 路线图。

免责声明

trello-mcp 是一个独立的社区维护项目。它不是 Trello 或 Atlassian 的官方产品、服务或 MCP 实现，也未与 Trello 或 Atlassian 建立关联、获得认可或赞助。

本项目旨在让兼容 MCP 的大模型客户端能够通过 Trello 的公开 API 和用户提供的 API 凭据，更轻松地与 Trello 交互。

想寻找 Trello 官方托管的 MCP 服务？请访问 Trello MCP，并使用 Trello 文档中列出的端点：https://mcp.trello.com/v1。

文档

完整的项目文档请访问 trello-mcp.com：

• 开始使用
• 创建 Trello API 密钥和令牌
• 设置 MCP 客户端
• 浏览工具目录
• 查看 API 覆盖范围和非目标
• 了解安全性和数据
• 运维已运行的部署
• 排查安装问题
• 官方 MCP Registry 安装、发布和恢复
• Glama 页面（验证状态）

功能

看板发现

• 列出经过身份验证的 Trello 成员可见的看板。
• 读取看板的基本元数据。
• 列出看板上的开放、已关闭或全部列表。
• 列出看板上的开放、已关闭、可见或全部卡片。
• 列出看板的标签、成员和成员关系。
• 创建、查看、更新和删除看板标签。
• 创建、查看、重命名、归档、取消归档列表，以及在看板之间移动列表。

卡片工作流

• 通过 ID、短 ID 或 Trello 卡片 URL 读取卡片。
• 创建卡片并设置标题、描述、截止日期、位置、成员和标签。
• 更新卡片元数据，包括标题、描述、截止日期、截止状态和归档状态。
• 在列表或看板之间移动卡片。
• 为卡片应用或移除现有标签。
• 仅在明确请求时永久删除卡片。

卡片上下文

• 列出 Trello 列表中的卡片。
• 列出卡片附件、查看单个附件、添加公开 URL 附件，以及从明确配置的目录上传服务器本地文件。
• 列出、创建、重命名和删除卡片检查清单，并管理检查清单项目。
• 列出卡片成员，以及添加或移除成员。
• 读取卡片操作和活动历史记录。
• 添加、编辑和删除 Trello 卡片评论。

搜索工作流

• 使用 Trello 搜索文本和运算符搜索 Trello 卡片、看板、成员和工作区。
• 将搜索结果限定在特定看板、卡片或工作区内。
• 按姓名或用户名查找 Trello 成员，然后再进行分配。
• 读取成员个人资料、已分配的卡片、看板和工作区。

工作区发现

• 列出经过身份验证的成员可见的 Trello 工作区。
• 读取工作区元数据、看板和成员。

自托管运行时

• 使用已发布的 GHCR 镜像，通过 Docker Compose 运行。
• 使用单独的 Compose 文件在本地构建。
• 容器部署使用 Streamable HTTP。
• 本地 MCP 客户端将服务作为子进程启动时，使用 stdio。
• 将 stdio 日志写入 stderr，确保本地 MCP 客户端接收到的 stdout 仅包含协议内容。
• 提供 HTTP 健康检查和就绪状态端点。
• 可选择要求 HTTP MCP 端点请求携带 Bearer 令牌。
• 使用 Zod 验证配置、工具输入和 Trello API 响应。
• 从日志中删去 Trello 凭据。
• 在 GitHub Actions 中运行类型检查、Lint、构建、测试和覆盖率检查。

快速开始

1. 获取 Trello API 凭据

Trello API 密钥通过 Trello 的 App 管理门户中的应用创建。运行此服务的每个人都应使用自己的 Trello 账户和令牌。请参阅专门的 Trello API 凭据指南，了解最新的安全操作步骤。

简而言之：在 trello.com/apps/admin 创建或选择一个应用，在其 API Key 标签页中生成密钥，然后使用旁边的 Token 链接，查看并授权目标 Trello 成员的访问权限。

你将使用这些值作为：

TRELLO_API_KEY=your-api-key
TRELLO_TOKEN=your-token

2. 选择安装方式

选项 A：运行已发布的 Docker 镜像

如果只想运行服务，请选择此方式。它会从 GHCR 拉取预构建镜像，不会在本地构建任何内容。

git clone https://github.com/enthouan/trello-mcp.git
cd trello-mcp
cp .env.example .env

编辑 .env 并替换占位值：

TRELLO_API_KEY=your-api-key
TRELLO_TOKEN=your-token
TRANSPORT=http
LOG_LEVEL=info
TRELLO_RATE_LIMIT_CAPACITY=100
TRELLO_RATE_LIMIT_REFILL_INTERVAL_MS=10000
TRELLO_RETRY_MAX_ATTEMPTS=3
TRELLO_RETRY_BASE_DELAY_MS=100
TRELLO_RETRY_MAX_DELAY_MS=2000
# MCP_AUTH_TOKEN=optional-shared-secret
TRELLO_MCP_HOST_BIND_IP=127.0.0.1
TRELLO_MCP_HOST_PORT=3000
TRELLO_MCP_IMAGE_TAG=latest
TRELLO_MCP_NETWORK=trello-mcp_network

启动已发布的镜像：

docker compose up -d --wait --wait-timeout 120

默认的 docker-compose.yml 使用：

ghcr.io/enthouan/trello-mcp:latest

Docker Compose 的镜像标签、主机绑定 IP、主机端口和网络名称等值可通过环境变量或 .env 文件覆盖。Compose 文件在顶部注明了默认值；例如，docker-compose.yml 中的 TRELLO_MCP_IMAGE_TAG 默认为 latest 标签（latest 跟随 main 分支，可使用 X.Y 和 X.Y.Z 等发布标签进行版本化部署），TRELLO_MCP_HOST_BIND_IP 默认为 127.0.0.1，仅允许本地访问；TRELLO_MCP_HOST_PORT 默认为 3000，会将该主机端口映射到容器内固定的 3000 监听端口；TRELLO_MCP_NETWORK 默认为 trello-mcp_network。只有在确实要让 Docker 在所有主机网络接口上发布服务（例如供局域网访问）时，才设置 TRELLO_MCP_HOST_BIND_IP=0.0.0.0。

将 MCP_AUTH_TOKEN 设为令牌，以要求对 /mcp 的 HTTP MCP 请求携带 Authorization: Bearer <token>。留空则默认采用未经身份验证的本地行为。健康和就绪端点仍不需要身份验证，以供容器和反向代理检查。

容器健康检查遵循 TRANSPORT：HTTP 模式会在 PORT（默认为 3000）上检查 /healthz；stdio 模式则检查进程是否存活，并由连接的 MCP 客户端检查协议响应情况。Compose 会继承此镜像健康检查。

除非日志在大型工作流期间显示 trello rate limit wait 或 trello request rate limited; retrying，否则请保留 Trello 速率限制和重试值的默认设置。对于共享令牌或资源受限的部署，请降低容量；只有在缩小工作流的看板、卡片、字段和分页范围后，才谨慎提高容量。

如需可重复的部署，请选择一个发布版本，并固定为经过验证的索引摘要。 请参阅镜像信任与只读验证， 了解 SBOM／来源信息检查、GHCR 签名策略，以及独立的 Docker 构建目录路径。元数据完整性检查并不能验证发布者身份。已发布 Docker 镜像标签采用以下约定：

标签	用途
latest	跟随当前 main 分支构建。仅在确实需要最新主分支镜像时使用。
X.Y	跟随次版本系列中的最新补丁版本，移动到由最新匹配的 vX.Y.Z 标签构建的镜像。
X.Y.Z	标识确切的发布版本，并由项目策略保留。固定其经过验证的摘要可确保字节内容不可变。
sha-<commit>	标识提交构建；稳定发布可将此别名修复为其经过验证的发布摘要。

也可以不使用 Compose，直接运行已发布的镜像：

docker run --rm -p 127.0.0.1:3000:3000 \
  -e TRELLO_API_KEY=your-api-key \
  -e TRELLO_TOKEN=your-token \
  ghcr.io/enthouan/trello-mcp:latest

选项 B：从源代码本地构建

如果要开发项目、测试本地更改或自行构建 Docker 镜像，请选择此方式。

本地开发使用 Node.js 24.x，并通过 Corepack 使用固定版本的 [email protected] 包管理器。

git clone https://github.com/enthouan/trello-mcp.git
cd trello-mcp
cp .env.example .env

在 .env 中填写 Trello 凭据，然后在本地构建并运行：

docker compose -f docker-compose.local.yml up --build -d --wait --wait-timeout 120

此方式使用 docker-compose.local.yml，从本地 Dockerfile 构建，并将镜像标记为 trello-mcp:local。

如需进行非 Docker 本地构建：

corepack enable
corepack prepare [email protected] --activate
corepack pnpm install --frozen-lockfile
corepack pnpm build:clean

然后直接运行编译后的服务：

TRELLO_API_KEY=your-api-key TRELLO_TOKEN=your-token TRANSPORT=stdio node dist/index.js

请像保护密码一样保护令牌。不要提交令牌、将其粘贴到日志中，或在 PR 中分享。

3. 连接 MCP 客户端

根据服务的运行位置选择传输方式：

你的设置	选择	客户端接收内容
构建好的克隆版本和 MCP 客户端位于同一台机器	stdio	本地命令，以及子进程环境中的 Trello 凭据
服务运行在 Docker 中、反向代理之后或另一台主机上	Streamable HTTP	/mcp URL 和可选的 bearer token；Trello 凭据保留在服务端

设置 MCP 客户端指南提供了适用于 Claude Desktop、Claude Code、Codex CLI、VS Code、OpenCode、MCP Inspector 及其他手动配置客户端的最新脱敏示例。指南还介绍了重启要求、HTTP bearer 支持、密钥处理和已测试的限制。

有关客户端版本及其证据的日期记录，请参阅 MCP 客户端兼容性。

4. 验证

如果你选择了 Streamable HTTP，请检查服务：

curl http://127.0.0.1:3000/healthz
curl http://127.0.0.1:3000/readyz

如果你修改了 TRELLO_MCP_HOST_PORT，请将 3000 替换为该主机端口。如果你将 TRELLO_MCP_HOST_BIND_IP 从 127.0.0.1 改成其他值，请使用能够访问已绑定主机接口的主机名或 IP 地址。

然后确认 MCP 客户端能够发现当前提供的 77 个工具。使用有意设置为只读的凭据检查方式，从客户端调用 auth_whoami 或 auth_token_info。不要仅为证明设置成功而调用会修改 Trello 数据的接口。

Trello 凭据

此服务目前使用 Trello API key + token 身份验证。请参阅专门的 Trello API 凭据指南，了解以安全为重点的操作说明，以及 Trello 官方 App Admin Portal、授权和撤销文档的链接。

使用只读的 auth_whoami 和 auth_token_info 工具，验证配置的凭据所验证的 Trello 成员身份，并检查已配置 token 的所有者、有效期和权限。这些工具仅用于诊断；此服务不实现 OAuth 重定向、token 创建、token 刷新、token 撤销或其他 token 生命周期管理功能。

设置 MCP 客户端

请参阅规范的设置 MCP 客户端指南，了解传输方式选择和针对特定客户端的配置。将 Trello 凭据保存在 stdio 子进程环境中或 HTTP 服务端；HTTP 客户端只需要 /mcp 端点，并且在启用 MCP_AUTH_TOKEN 时，需要使用受支持的 bearer-header 配置。

兼容性记录区分了对官方文档的审核与实际客户端连接、工具发现和真实 Trello 工作流。

环境

请参阅配置参考，了解特定部署的适用性、密钥处理、速率限制调优、Compose 控制项以及本地附件上传要求。

变量	必填	默认值	描述
TRELLO_API_KEY	是		Trello API 密钥。
TRELLO_TOKEN	是		用于令牌身份验证的 Trello 令牌。
MCP_AUTH_TOKEN	否		如果设置，向 /mcp 发送的 HTTP MCP 请求必须包含 Authorization: Bearer <token>。留空则不进行 HTTP Bearer 令牌检查。
TRELLO_ATTACHMENT_UPLOAD_ROOT	否		用于启用本地文件附件上传的服务器端绝对目录。留空则禁用本地上传。
TRELLO_RATE_LIMIT_CAPACITY	否	100	Trello 请求的令牌桶容量；令牌耗尽后客户端将等待令牌补充。必须为正整数。
TRELLO_RATE_LIMIT_REFILL_INTERVAL_MS	否	10000	令牌桶补充间隔，单位为毫秒。必须为正整数。
TRELLO_RETRY_MAX_ATTEMPTS	否	3	Trello 返回 HTTP 429 时，Trello 请求的总尝试次数。必须为正整数。
TRELLO_RETRY_BASE_DELAY_MS	否	100	HTTP 429 重试的指数退避基础延迟，单位为毫秒，并带有限幅抖动。必须为正整数。
TRELLO_RETRY_MAX_DELAY_MS	否	2000	任意 HTTP 429 重试等待的最大延迟，单位为毫秒。必须为正整数。
TRANSPORT	否	http	http 或 stdio。
PORT	否	3000	Node 进程的 HTTP 监听端口。Docker Compose 将容器监听端口保持为 3000，并使用 TRELLO_MCP_HOST_PORT 设置发布到主机的端口。
LOG_LEVEL	否	info	Pino 日志级别。
TRELLO_MCP_HOST_BIND_IP	否	127.0.0.1	Docker Compose 主机网络接口绑定地址。仅供本地访问时保持为 127.0.0.1；如需有意向网络／局域网公开服务，则设置为 0.0.0.0，以在所有主机接口上发布。
TRELLO_MCP_HOST_PORT	否	3000	Docker Compose 主机端口，映射到容器固定的内部监听端口 3000。
TRELLO_MCP_IMAGE_TAG	否	latest	已发布的镜像标签；latest 跟随 main，X.Y 跟随该次要版本系列中的最新补丁版本，X.Y.Z 则固定到指定版本。
TRELLO_MCP_NETWORK	否	trello-mcp_network	Docker Compose 桥接网络名称。

Trello 实时冒烟测试

常规测试使用模拟数据，且离线运行。corepack pnpm test、corepack pnpm test:coverage 和默认 CI 工作流都不需要 Trello 凭据，也不会联系 Trello。

如需针对真实 Trello 进行发布验证，请使用明确的实时冒烟命令：

TRELLO_LIVE_SMOKE=1 \
TRELLO_LIVE_SMOKE_BOARD_ID=your-disposable-board-id-or-short-link \
TRELLO_API_KEY=your-api-key \
TRELLO_TOKEN=your-token \
corepack pnpm smoke:live

你可以使用 TRELLO_LIVE_SMOKE_BOARD_URL 代替 TRELLO_LIVE_SMOKE_BOARD_ID；Trello 的 trello.com/b/... 看板 URL 会被规范化为短链接，然后测试框架会先通过 board_get 获取规范看板 ID，再创建任何内容。非看板 URL 会被拒绝，且不会记录其原始值或查询字符串。TRELLO_LIVE_SMOKE_RUN_ID 是可选的；设置后，该值会包含在临时产物名称中。

当输出可能会公开发布时，请设置 TRELLO_LIVE_REQUIRE_PUBLIC_BOARD=1。此时，测试框架会先验证 Trello 报告的看板为公开状态，再记录其身份或执行写入操作。对于本地私有的一次性看板验证，此设置是可选的。

安全模型：

• 除非同时设置 TRELLO_LIVE_SMOKE=1、Trello 凭据以及冒烟看板 ID 或 URL，否则命令会在发送任何 Trello 请求之前退出。
• 配置的看板应是专用于验证的一次性看板，而非活跃的生产看板。
• 测试框架会创建名称唯一的临时列表、一张卡片、一个标签、一个清单、一个清单项目和一条评论。它会删除卡片和标签，将临时列表归档，并验证没有剩余的未关闭临时列表、卡片或标签。
• 即使中间验证步骤失败，也会执行清理。它还会搜索 Trello 已创建、但因响应验证失败而未能记录的唯一前缀列表、卡片和标签。清理失败会被报告，并导致命令失败。
• 测试框架使用真实的 TrelloClient 调用现有工具处理程序，因此工具输入验证、Trello 响应验证、重试／速率限制处理以及凭据脱敏都沿用正常代码路径。
• 测试框架不会记录 API 密钥、令牌、包含凭据的 URL、原始环境对象或原始请求数据。

冒烟流程会验证有代表性的 v1.0 工作流：

• 身份验证与发现：auth_whoami、auth_token_info、list_boards、看板读取、列表、卡片、标签、成员、成员资格和自定义字段发现。
• 列表与卡片写入：创建／重命名／归档一次性列表；创建／读取／更新／设置到期日期／调整位置／归档／恢复／移动／删除卡片。
• 清单与项目行为：创建／重命名／删除清单，以及创建／列出／更新／勾选／删除项目。
• 标签与成员：创建／读取／更新／应用／移除／删除一次性标签；如果已认证成员显示在冒烟看板上，还会将其分配到卡片或从卡片移除。
• 卡片活动：在一次性卡片上创建／更新／列出／删除评论。

Trello 实时回归测试

corepack pnpm smoke:live 是浅层发布冒烟检查：它会验证最重要的工作流能否完成身份验证、创建一次性产物、修改这些产物并进行清理。corepack pnpm regression:live 是范围更广的自选加入发布验证套件。它会按领域遍历公开的 MCP 工具接口，报告相对于已注册工具目录的实时覆盖情况，并明确显示跳过或缺失的实时覆盖项。

回归套件有独立于冒烟测试的自选加入门槛：

TRELLO_LIVE_REGRESSION=1 \
TRELLO_LIVE_REGRESSION_BOARD_ID=your-disposable-board-id-or-short-link \
TRELLO_API_KEY=your-api-key \
TRELLO_TOKEN=your-token \
corepack pnpm regression:live

如果使用 trello.com/b/... 看板 URL 更方便，可以使用 TRELLO_LIVE_REGRESSION_BOARD_URL 代替 TRELLO_LIVE_REGRESSION_BOARD_ID。非看板 URL 会在发送任何 Trello 请求之前被拒绝，且不会记录原始查询字符串。

当输出或 JSON 报告可能会公开发布时，请设置 TRELLO_LIVE_REQUIRE_PUBLIC_BOARD=1。此时，测试框架会先验证 Trello 报告的每个已配置看板均为公开状态，再记录其身份或执行写入操作。本地私有的一次性看板运行可以省略此标志，并将输出保留为私有。 如果需要对跨看板移动列表进行实时覆盖测试，请设置 TRELLO_LIVE_REGRESSION_SECONDARY_BOARD_ID 或 TRELLO_LIVE_REGRESSION_SECONDARY_BOARD_URL。本地运行时，次要看板是可选的；如果未设置，则会将 list_move_to_board 报告为有意跳过的运行时测试，而不是缺少覆盖测试。如果已设置，测试套件会通过 board_get 解析该看板，确认令牌可通过 list_boards 查看该看板，验证看板处于开放状态且与主看板不同，然后仅在两个看板之间移动可丢弃的列表。

在调试某个领域或某个工具时，定向运行很有用：

TRELLO_LIVE_REGRESSION=1 \
TRELLO_LIVE_REGRESSION_BOARD_ID=your-disposable-board-id-or-short-link \
TRELLO_API_KEY=your-api-key \
TRELLO_TOKEN=your-token \
corepack pnpm regression:live --domain cards

TRELLO_LIVE_REGRESSION=1 \
TRELLO_LIVE_REGRESSION_BOARD_ID=your-disposable-board-id-or-short-link \
TRELLO_API_KEY=your-api-key \
TRELLO_TOKEN=your-token \
corepack pnpm regression:live --tool card_attachment_upload

TRELLO_LIVE_REGRESSION=1 \
TRELLO_LIVE_REGRESSION_BOARD_ID=your-primary-disposable-board-id-or-short-link \
TRELLO_LIVE_REGRESSION_SECONDARY_BOARD_ID=your-secondary-disposable-board-id-or-short-link \
TRELLO_API_KEY=your-api-key \
TRELLO_TOKEN=your-token \
corepack pnpm regression:live --tool list_move_to_board

你也可以使用 TRELLO_LIVE_REGRESSION_DOMAINS=cards,attachments 和 TRELLO_LIVE_REGRESSION_TOOLS=card_get,card_update。支持的领域包括 auth、boards、lists、cards、labels、checklists、members、workspaces、search、custom-fields、comments-actions 和 attachments。

设置 TRELLO_LIVE_REGRESSION_REPORT_JSON=reports/live-regression.json，即可在生成可供机器读取的报告的同时，生成可供人阅读的终端报告。报告按领域对工具分组，并显示：

• covered：已成功通过 Trello 执行测试的工具处理程序。
• skipped：有意跳过的运行时测试，例如没有可见工作区、没有看板自定义字段，或未配置上传覆盖测试。
• unsupported：有意排除在回归覆盖范围之外的非目标实时测试用例，例如 board_create。
• missing：未分类回归覆盖情况的已选公共工具。缺少覆盖测试会导致命令失败，以免新公共工具在发布验证中被悄然遗漏。
• 清理状态，包括尝试和完成的清理步骤，以及任何仍然存在且名称匹配前缀的开放产物。

回归测试的安全模型：

• 除非同时设置 TRELLO_LIVE_REGRESSION=1、Trello 凭据，以及回归看板 ID 或 URL，否则命令会在发出任何 Trello 请求前退出。
• 配置的看板应为专门用于验证的可丢弃看板，而非正在使用的生产看板。
• 可选的次要看板也应为可丢弃看板。只有在执行 list_move_to_board 时才会修改它，且只会操作本次回归运行创建的列表。
• 临时产物使用唯一的运行 ID 和 trello-mcp live regression ... 前缀。需要易读的运行标记时，请设置 TRELLO_LIVE_REGRESSION_RUN_ID。
• 即使中间步骤失败，也会执行清理。清理操作会移除已跟踪的临时卡片、标签、附件、成员／标签分配、自定义字段值，并归档临时列表。它还会搜索所有已配置的回归看板，查找响应尚未被跟踪前创建的、名称匹配前缀的列表、卡片和标签。
• 测试套件通过真实的 TrelloClient 调用已注册的工具处理程序；不会通过单独临时创建的客户端调用 Trello。
• 测试套件不会记录 API 密钥、令牌、包含凭据的 URL、原始环境对象或原始请求数据。

本地文件上传覆盖测试默认跳过。若要纳入 card_attachment_upload，必须同时配置常规上传根目录和明确指定的回归测试文件：

TRELLO_ATTACHMENT_UPLOAD_ROOT=/absolute/path/to/trello-uploads \
TRELLO_LIVE_REGRESSION_UPLOAD_FILE=sample.txt \
TRELLO_LIVE_REGRESSION=1 \
TRELLO_LIVE_REGRESSION_BOARD_ID=your-disposable-board-id-or-short-link \
TRELLO_API_KEY=your-api-key \
TRELLO_TOKEN=your-token \
corepack pnpm regression:live --domain attachments

上传文件路径可以是相对于 TRELLO_ATTACHMENT_UPLOAD_ROOT 的路径，也可以是绝对路径，但解析后的路径必须位于上传根目录内。

如果本地验证期间未设置实时环境变量，请将实时命令记录为已跳过。跳过状态会明确显示：corepack pnpm smoke:live 和 corepack pnpm regression:live 会在联系 Trello 前失败退出，并打印缺少的变量名称。除非某个 CI 作业明确配置为使用密钥且选择加入，否则不要将这两个命令加入常规 CI。

GitHub Actions

仓库包含一个 Live Trello Smoke 工作流，用于 PR、合并到 main 后的验证以及发布验证。它会在同一仓库的拉取请求、推送到 main 以及手动触发时运行。跳过来自 Fork 的拉取请求，以免向不受信任的 PR 代码暴露 Trello 凭据。

该工作流会先运行离线检查（pnpm typecheck、pnpm lint、pnpm build 和 pnpm test），然后才运行需要密钥的实时冒烟测试步骤。

使用前，请配置一个名为 live-smoke 的 GitHub Environment，并设置以下密钥：

密钥	说明
TRELLO_LIVE_SMOKE_API_KEY	专用冒烟测试 Trello 成员的 Trello API 密钥。
TRELLO_LIVE_SMOKE_TOKEN	同一成员的 Trello 令牌，对临时冒烟测试看板具有写入权限。

如果仓库有多位维护者，或令牌可以访问冒烟测试看板以外的内容，请使用 Environment 的必需审核者设置。该工作流仅在 pnpm smoke:live 步骤中将这些密钥映射为 TRELLO_API_KEY 和 TRELLO_TOKEN。作业设置了 environment.deployment: false，因此 GitHub Environment 仍会限定密钥的作用范围并应用保护规则，但不会创建 Deployment 记录。不要对此工作流使用 pull_request_target。

托管的冒烟测试工作流固定使用公开的临时测试看板短链接 hUaItfNq，并设置 TRELLO_LIVE_REQUIRE_PUBLIC_BOARD=1，因此如果 Trello 不再将该看板报告为公开看板，工作流会在输出身份信息或写入数据之前失败。它不接受看板覆盖值，因此维护者不会意外通过公开的 Actions 日志或摘要泄露私有看板的标识符。当临时项目名称和活动历史记录可能被看到时，公开看板可用于冒烟测试；但公开可见并不意味着不需要 Trello 凭据，因为测试程序会执行写入操作。对于其他临时看板，请使用上方的本地命令，并避免将私有看板的输出写入公开日志和构建产物。

范围更广的 Live Trello Regression 工作流仅支持手动触发，应当用于发布候选版本或有针对性的实时调试，而不是作为常规 PR 检查门禁。配置一个名为 live-regression 的 GitHub Environment，并设置：

密钥	说明
TRELLO_LIVE_REGRESSION_API_KEY	专用回归测试 Trello 成员的 Trello API 密钥。
TRELLO_LIVE_REGRESSION_TOKEN	同一成员的 Trello 令牌，对临时回归测试看板具有写入权限。

托管的回归测试工作流固定使用公开的临时主看板和次看板 hUaItfNq 与 r9BpowfZ，并设置 TRELLO_LIVE_REQUIRE_PUBLIC_BOARD=1，因此如果 Trello 不再将任一看板报告为公开看板，工作流会在输出身份信息或写入数据之前失败。它接受可选的 domains 和 tools 输入，并会在命令生成 reports/live-regression.json 时上传该文件。如需使用其他看板，请在本地运行命令，并且不要发布私有看板的报告。该工作流还设置了 environment.deployment: false，因为实时回归测试是需要密钥的验证，而不是应用部署。不得向 Fork 的拉取请求提供 Trello 凭据；请将实时回归测试保留为 workflow_dispatch 或其他明确需要密钥的工作流。

Release 工作流会在推送到 main 和 v*.*.* 标签时，为 linux/amd64 和 linux/arm64 构建已发布的多架构 Docker 镜像。也可以从某个分支手动运行，并设置 push=false，以便在发布镜像相关更改合并前进行多平台验证。试运行时保持 push=false；仅在确实要发布到 GHCR 时使用 push=true。

使用示例

连接到 MCP 客户端后，可以用自然语言请求 Trello 操作：

对于先检查、多工具串联且包含明确提案、批准和验证阶段的操作，请参阅工作流指南。

Show me my Trello boards.
Show me the lists on my job scout board.
Show me the cards in my "Today" list.
Create a card called "Review invoices" in the bookkeeping list.
Move this card to Done.
Archive the card about the old onboarding checklist.
Show the recent activity for this card.
Add a comment to this card saying the invoices are ready for review.
Edit this card comment to include the updated invoice total.
Add this public URL as an attachment to the card.
Upload the file invoice.pdf from my Trello upload folder to this card.
Show me the custom fields configured on this board.
Set this card's Priority custom field to the High option.
Clear this card's Estimate custom field.

具体措辞取决于你的 MCP 客户端。服务可以先发现你的看板和看板列表，然后使用这些 ID 执行卡片工作流。

大型 Trello 响应

集合工具默认以精简模式读取 Trello 数据，避免 MCP 客户端收到不必要的大型载荷。高容量的卡片、标签和操作读取默认使用 limit: 50；Trello 将这些集合读取的上限设为 1000。

使用 fields 仅请求工作流所需的属性。验证对象名称、ID 或操作类型的工具会自动添加架构要求的字段，即使你请求的字段集更小也是如此。仅在详细的后续读取确实需要更大响应时，才使用 fields: "all"。

在卡片集合和操作工具中使用 since 和 before，按页读取较旧或较新的 Trello 对象。这些游标接受 ISO-8601 时间戳、Trello/Mongo ID，或 Trello 支持时的 null。操作读取还会公开从 0 开始的 page，用于 Trello 的操作分页。

使用 card_actions、board_actions、list_actions 和 workspace_actions 执行范围明确的活动审计。设置 filter: "commentCard" 以筛选评论，设置 filter: "all" 以查看更广泛的活动，并结合使用 limit、since、before 和 page，让看板、列表、卡片或工作区历史记录保持足够精简，适合 MCP 客户端处理。

返回成员信息的工具默认使用精简的成员字段（username,fullName,initials,avatarUrl）。如果工作流需要其他成员资料属性，可使用 fields、memberFields 或 memberCreatorFields 等成员字段输入参数。

搜索

当用户提供自然语言词语，而你需要在采取操作前查找匹配的卡片或看板时，使用 search。它默认搜索卡片和看板，返回精简字段，并且每种资源类型默认返回 10 条结果。如果成员或工作区结果类型有用，可将 members 或 organizations 添加到 modelTypes。

使用 boardIds: "mine" 或指定看板 ID，以缩小卡片和看板搜索范围。使用 organizationIds 指定工作区 ID，并根据需要使用 cardIds、partial、cardsPage 以及各类型的限制输入参数，以进一步缩小查询范围或进行分页。使用 search_members 按姓名或用户名查找受指派人，尤其适用于指定看板或工作区范围的查询。

附件上传

公开 URL 附件无需额外设置即可使用。虽然支持本地文件上传，但默认禁用，因为 MCP 客户端会要求服务进程从服务端文件系统读取文件。

要启用 card_attachment_upload，请将 TRELLO_ATTACHMENT_UPLOAD_ROOT 设置为服务可读取的绝对目录路径。上传工具的 filePath 值可以是相对于该目录的路径，也可以是最终仍指向该目录内文件的绝对路径。服务会使用 realpath 解析符号链接，在发送任何 Trello 请求前拒绝目录和配置根目录之外的文件。

用于本地 stdio：

TRELLO_ATTACHMENT_UPLOAD_ROOT=/Users/you/trello-uploads \
  TRELLO_API_KEY=your-key \
  TRELLO_TOKEN=your-token \
  TRANSPORT=stdio \
  node dist/index.js

用于 Docker，将上传目录挂载到容器中，并将根目录设置为容器内的路径：

docker run --rm -p 127.0.0.1:3000:3000 \
  -v "$PWD/trello-uploads:/uploads:ro" \
  -e TRELLO_ATTACHMENT_UPLOAD_ROOT=/uploads \
  -e TRELLO_API_KEY=your-api-key \
  -e TRELLO_TOKEN=your-token \
  ghcr.io/enthouan/trello-mcp:latest

MCP 客户端不会通过此工具直接上传字节数据；它们会提供一个必须存在于服务端主机或容器内的路径。对于远程服务，请先将文件复制或挂载到 TRELLO_ATTACHMENT_UPLOAD_ROOT 中。

自定义字段

自定义字段定义位于 Trello 看板上，卡片值通过卡片的 customFieldItems 暴露。使用 board_custom_fields 查找看板级字段定义及其 ID，使用 custom_field_options 列出字段的下拉列表选项，使用 card_custom_field_items 查看卡片当前设置的值。

写入工具 card_custom_field_set 一次接受一个自定义字段，并使用特定于类型的输入格式：

自定义字段类型	输入格式	说明
text	{ "type": "text", "text": "Hello" }	纯文本值。
number	{ "type": "number", "number": "42" }	Trello 要求将数字作为字符串传递。
date	{ "type": "date", "date": "2026-06-03T16:00:00.000Z" }	必须是 ISO-8601 日期/时间字符串。
checkbox	{ "type": "checkbox", "checked": true }	服务会向 Trello 发送 Trello 所需的字符串值。
list	{ "type": "list", "optionId": "<custom-field-option-id>" }	使用 board_custom_fields 或 custom_field_options 查找选项 ID。

使用 card_custom_field_clear 清除卡片上已有的自定义字段值。Trello 通过空 PUT 请求格式而非 DELETE 请求来清除自定义字段项，因此清除操作与设置值的操作分开处理。

创建看板

board_create 会创建新的 Trello 看板，prefs_permissionLevel 默认值为 private。传入 workspaceId 可将看板放入 Trello 工作区/组织；仅当你希望看板对工作区可见（org）或公开（public）时，才显式设置 permissionLevel。

API 覆盖范围

请参阅 docs/api-coverage.md，了解 Trello REST API 分组覆盖范围矩阵、暂缓支持的端点系列以及当前不在目标范围内的内容。

工具目录

已注册 77 个工具。名称、描述和关键输入均由 allTools 生成。

名称	使用时机	关键输入
auth_whoami	用作只读凭据诊断，确认配置的 API 密钥和令牌以哪个 Trello 成员的身份进行身份验证。	fields
auth_token_info	用作只读凭据诊断，检查配置的 Trello 令牌的所有者、到期时间和权限；它不会创建、刷新、撤销或管理令牌。	fields
list_boards	当用户未提供看板、列表、卡片 ID 或 Trello URL 时优先使用；返回经过身份验证的 Trello 成员可见的看板。	filter, fields
board_create	创建新的 Trello 看板时使用。默认将看板创建为私有，可通过 workspaceId 将其放入工作区，并且仅支持明确设置为私有、工作区或公开可见。	name, desc, workspaceId, permissionLevel
board_get	在列出或汇总已知 Trello 看板之前，需要看板详情、常用看板偏好设置或标签名称时使用。	boardId, fields
board_field_get	需要获取某个具体看板字段时使用，例如 prefs、labelNames、subscribed、name、description 或 URL。	boardId, field
board_actions	审查看板中的近期活动或评论时使用；使用 filter、limit、page、since、before 和 fields 限制大型历史记录的范围。	boardId, filter, fields, limit, since, before, page, member, memberFields, memberCreator, memberCreatorFields
board_lists	需要获取已知 Trello 看板中的列表，以便在列出或创建卡片前找到正确的列表 ID 时使用。	boardId, filter, fields
board_cards	需要获取已知 Trello 看板所有列表中的卡片，用于个人计划、审查或汇总时使用。	boardId, filter, fields, limit, since, before
board_custom_fields	检查已知 Trello 看板上的自定义字段定义时使用，包括 Trello 返回的下拉列表选项。	boardId
board_labels	在创建或更新卡片并添加标签之前，查找看板上可用的标签时使用。	boardId, limit, fields
board_members	在分配卡片或审查协作情况之前，需要获取可访问已知 Trello 看板的成员时使用；令牌必须能查看私有看板。	boardId, fields
board_memberships	需要获取已知 Trello 看板的成员资格记录、成员角色或权限上下文时使用；检查仅限看板管理员执行的操作时，使用 admins 筛选条件。	boardId, filter, member, memberFields
list_workspaces	用户要求显示 Trello 工作区，或需要先选择工作区再查看其中的看板或成员时优先使用。	filter, fields, paidAccount
workspace_get	需要获取 Trello 工作区的基本元数据时使用，例如显示名称、描述、URL、网站、看板 ID 或偏好设置。	workspaceId, fields
workspace_boards	需要获取已知 Trello 工作区中的看板，以便用户进一步查看工作区中的某个看板时使用。	workspaceId, filter, fields
workspace_members	在分配任务、审查记录或检查权限之前，需要获取已知 Trello 工作区中的成员时使用。	workspaceId, filter, fields
workspace_actions	审查 Trello 工作区中的近期活动或评论时使用；使用 filter、limit、page、since、before 和 fields 限制大型历史记录的范围。	workspaceId, filter, fields, limit, since, before, page, member, memberFields, memberCreator, memberCreatorFields
member_get	成员搜索或列出看板成员后，在分配任务或审查记录之前，通过 ID、用户名或 me 检查 Trello 成员资料时使用。	memberId, fields
member_boards	需要获取与已知 Trello 成员关联的看板时使用，成员可通过 ID、用户名或 me 指定；结果仅限配置的令牌可见的看板。	memberId, filter, fields
member_cards	需要获取分配给已知 Trello 成员的卡片时使用，成员可通过 ID、用户名或 me 指定；访问私有看板卡片需要令牌拥有这些看板的访问权限。	memberId, filter, fields, limit, since, before
member_workspaces	需要获取与已知成员关联的 Trello 工作区时使用，成员可通过 ID、用户名或 me 指定；结果受工作区可见性和角色权限限制。	memberId, filter, fields, paidAccount
list_get	在创建卡片或更改已知 Trello 列表之前，需要获取其元数据时使用。	listId, fields
list_create	在现有看板上创建新的 Trello 列表时使用。	boardId, name, pos
list_update	重命名 Trello 列表、更改其位置或设置其归档状态时使用。	listId, name, closed, pos
list_archive	归档或取消归档 Trello 列表，同时保留其卡片以供恢复时使用。	listId, closed
list_move_to_board	将现有列表及其卡片移至另一看板，从而更改其访问权限。要在当前看板内重新排序，请使用 list_update。	listId, boardId
list_actions	审查列表的近期活动或评论时使用；使用 filter、limit、page、since、before 和 fields 限制大型历史记录的范围。	listId, filter, fields, limit, since, before, page, member, memberFields, memberCreator, memberCreatorFields
card_get	在编辑或汇总之前，需要通过 ID、短链接或 URL 获取某张 Trello 卡片的当前详情时使用。	cardId, fields
card_board	在移动、添加标签或汇总上下文之前，需要获取已知 Trello 卡片与看板的关联关系时使用。	cardId, fields
card_list	在移动卡片或报告其状态之前，需要获取已知 Trello 卡片与列表的当前关联关系时使用。	cardId, fields
card_labels	列出当前应用于卡片的标签时使用，包括用于添加/移除工作流的标签 ID。	cardId
list_cards	需要获取特定 Trello 列表中的卡片时使用；使用 limit、since、before 和 fields 限制大型列表的范围。	listId, filter, fields, limit, since, before
card_create	用户要求在已知列表中创建新的 Trello 卡片时使用；可接受标题、描述、到期日期、成员和标签。	listId, name, desc, due, pos, memberIds, labelIds
card_update	更改卡片元数据时使用，例如标题、描述、到期日期、到期完成状态或归档状态，但不移动卡片。	cardId, name, desc, due, dueComplete, closed
card_due_date_set	设置、清除卡片到期日期或标记其完成状态，同时不更改其他卡片元数据时使用。至少提供 due 或 dueComplete 之一。	cardId, due, dueComplete
card_position_set	仅更改卡片在当前列表中的位置时使用；如果还要更改列表或看板，请使用 card_move。	cardId, pos
card_cover_set	将卡片封面设为现有附件 ID、更改封面显示尺寸或清除当前附件封面时使用。	cardId, attachmentId, size, brightness
card_label_create_and_add	创建新的看板标签并将其应用于此卡片。现有标签请使用 card_label_add；重复创建可能产生重复标签。	cardId, name, color
card_delete	仅在用户明确要求永久删除 Trello 卡片时使用；如需可撤销地移除，请改为归档。	cardId
card_move	将卡片移至另一列表、另一看板或不同位置时使用；这与一般卡片元数据更新不同。	cardId, listId, boardId, pos
card_archive	用户希望归档或取消归档卡片并保留其以供恢复时使用；不要用于永久删除。	cardId, closed
card_attachments	列出卡片附加的文件或链接时使用，可选择按 Trello 附件字段或筛选条件缩小范围。	cardId, fields, filter
card_attachment_get	检查某个现有卡片附件时使用，需提供附件 ID；包括 Trello 返回的上传元数据。	cardId, fields, attachmentId
card_attachment_add_url	将现有公开 URL 附加到卡片时使用；此工具不会上传本地文件。	cardId, url, name, setCover
card_attachment_upload	读取 TRELLO_ATTACHMENT_UPLOAD_ROOT 中的服务器本地文件，并将其内容传输到 Trello，作为新的卡片附件。仅在配置该目录后启用；重复上传可能产生重复附件。公开链接请使用 card_attachment_add_url。	cardId, filePath, name, mimeType, setCover
card_attachment_delete	永久删除卡片附件，包括 Trello 存储的上传文件。此操作无法撤销；如果只需清除封面而不删除附件，请使用 card_cover_set。	cardId, attachmentId
card_checklists	查看卡片上当前所有检查清单及其条目时使用。	cardId
card_checklist_create	向现有卡片添加新的检查清单时使用，可选择从其他检查清单复制。	cardId, name, sourceChecklistId
card_checklist_update	重命名 Trello 卡片检查清单或更改其在卡片上的位置时使用。至少提供 name 或 pos 之一。	checklistId, name, pos
card_checklist_delete	永久删除卡片上的检查清单及其所有条目。此操作无法撤销；若只需删除一个条目，请使用 card_checklist_item_delete。	cardId, checklistId
card_checklist_item_create	向卡片上现有的 Trello 检查清单添加新条目时使用。	checklistId, name, pos, checked, due, dueReminder, memberId
card_checklist_items	列出某个 Trello 检查清单中的条目时使用，默认包括已完成和未完成的条目。	checklistId, filter, fields
card_checklist_item_update	编辑 Trello 卡片检查清单条目的文本、到期日期、成员分配、完成状态、所属检查清单或位置时使用。	cardId, checkItemId, name, state, checklistId, pos, due, dueReminder, memberId
card_checklist_item_set_checked	勾选或取消勾选 Trello 卡片检查清单条目，同时不更改其他条目字段时使用。	cardId, checkItemId, checked
card_checklist_item_move	将 Trello 检查清单条目移至同一卡片上的另一检查清单，或更改其位置时使用。	cardId, checkItemId, checklistId, pos
card_checklist_item_delete	永久删除一个检查清单条目。此操作无法撤销；若要标记为已完成并保留该条目，请使用 card_checklist_item_set_checked。	cardId, checkItemId
card_custom_field_items	读取 Trello 卡片上当前设置的所有自定义字段值时使用。	cardId
card_custom_field_set	设置或替换某个卡片自定义字段值，使用 custom_field_get 获取现有定义的类型。使用 custom_field_options 查找列表选项 ID，使用 card_custom_field_clear 移除值。	cardId, customFieldId, type, text, number, date, checked, optionId
card_custom_field_clear	清除某张卡片的一个自定义字段值，但不删除看板的字段定义。要恢复该值，需使用 card_custom_field_set 重新设置之前的值。	cardId, customFieldId
card_members	列出分配给卡片的成员时使用；令牌必须能访问卡片所属的看板。使用 fields 减少成员输出内容。	cardId, fields
card_member_add	通过成员 ID 将 Trello 成员分配给卡片时使用；需要拥有卡片看板的写入权限，且该成员必须能够分配到该看板。	cardId, memberId
card_member_remove	通过成员 ID 取消将 Trello 成员分配给卡片时使用；需要拥有卡片看板的写入权限。	cardId, memberId
card_comment_add	向 Trello 卡片添加新评论并返回其评论操作记录。重复调用会创建另一条评论；要编辑现有评论，请使用 card_comment_update。	cardId, text
card_comment_update	通过评论操作 ID 编辑现有 Trello 卡片评论文本时使用。	actionId, text
card_comment_delete	通过操作 ID 永久删除卡片评论。此操作无法撤销；要改为编辑文本，请使用 card_comment_update。	actionId
card_actions	审查卡片的近期活动或评论时使用；使用 filter、limit、page、since、before 和 fields 对大型历史记录进行分页。	cardId, filter, fields, limit, since, before, page, member, memberFields, memberCreator, memberCreatorFields
label_get	编辑特定 Trello 标签之前，需要获取其当前名称、颜色或所属看板时使用。	labelId
label_create	在将新标签应用于卡片之前，创建可在 Trello 看板上重复使用的标签时使用。	boardId, name, color
label_update	重命名 Trello 标签或更改其颜色，同时不更改任何卡片上的标签分配时使用。	labelId, name, color
label_delete	仅在用户明确要求永久删除看板标签时使用；这会从所有使用该标签的卡片中移除标签。若只需取消其在一张卡片上的分配并保留标签，请使用 card_label_remove。	labelId
card_label_add	通过标签 ID 将现有 Trello 标签应用于卡片时使用。	cardId, labelId
card_label_remove	通过标签 ID 从卡片中移除现有 Trello 标签时使用。	cardId, labelId
custom_field_get	需要获取某个 Trello 自定义字段定义时使用，包括其类型以及 Trello 返回的任何下拉列表选项。	customFieldId
custom_field_options	设置卡片列表自定义字段值之前，列出 Trello 下拉列表自定义字段的可用选项时使用。	customFieldId
search	搜索 Trello，并返回令牌可见的卡片、看板、成员和工作区分组结果。默认搜索卡片和看板；可限制范围和结果数量，并使用 cardsPage 对卡片结果分页。要专门查找成员，请使用 search_members。	query, modelTypes, boardIds, organizationIds, cardIds, cardFields, boardFields, memberFields, organizationFields, cardsLimit, boardsLimit, membersLimit, organizationsLimit, cardsPage, partial, includeCardBoard, includeCardList, includeCardMembers, includeBoardOrganization
search_members	按名称或用户名查找 Trello 成员，可选择限定在某个看板或工作区内；限定范围的搜索要求令牌能够访问该看板或工作区。	query, limit, boardId, organizationId, onlyOrgMembers
使用以下命令重新生成目录：

corepack pnpm docs:tools

架构

请阅读 trello-mcp 的工作原理，了解完整的请求生命周期、传输方式和凭据边界、HTTP 会话、验证、速率限制、重试及结果处理。

MCP client
  -> stdio or Streamable HTTP transport
  -> MCP server and tool registry
  -> Trello tool handlers
  -> Trello REST client
  -> Trello REST API

• src/index.ts 启动 stdio 或 HTTP 传输。
• src/server.ts 创建 MCP 服务并注册工具。
• src/http-auth.ts 在 HTTP MCP 请求中强制执行可选的 MCP_AUTH_TOKEN bearer 验证。
• src/trello/auth.ts 定义只读的 auth_whoami 和 auth_token_info 凭据诊断工具。
• src/trello/client.ts 负责 Trello HTTP 请求、身份验证查询参数、重试和响应解析。
• src/trello/boards.ts 定义看板发现，以及看板级别的列表、卡片、标签、成员和自定义字段工具。
• src/trello/workspaces.ts 定义工作区发现、元数据、看板和成员工具。
• src/trello/members.ts 定义成员个人资料、看板、卡片和工作区查询工具。
• src/trello/lists.ts 定义列表创建、检查、更新、归档和移动工具。
• src/trello/cards.ts 定义卡片工具，包括附件、清单、成员、评论、操作和卡片自定义字段项辅助工具。
• src/trello/labels.ts 定义标签 CRUD 和卡片标签分配工具。
• src/trello/custom-fields.ts 定义自定义字段定义和选项查询工具。
• src/trello/search.ts 定义卡片、看板、成员和工作区搜索工具。
• src/trello/fields.ts 定义共享的 Trello 字段列表验证辅助工具。
• src/trello/types.ts 包含 Trello 响应架构。
• src/utils/* 包含日志记录、错误映射、分页和工具注册辅助工具。

安全说明

• Trello 凭据保留在你的环境或 MCP 客户端配置中。
• 日志会隐去 TRELLO_API_KEY、TRELLO_TOKEN、MCP_AUTH_TOKEN、授权标头以及常见的密钥／令牌字段。
• Trello API 请求使用 HTTPS。
• 设置 MCP_AUTH_TOKEN，为 HTTP MCP 流量启用基本的共享密钥验证。这不能替代 HTTPS、反向代理身份验证、IP 允许列表或谨慎的主机绑定。
• 除非配置了 TRELLO_ATTACHMENT_UPLOAD_ROOT，否则会禁用本地文件附件上传；上传路径仅限于该目录。
• 测试使用模拟对象和注入的 fetcher，而不调用线上 Trello。
• 请勿发布 .env 文件，也不要在 issue 和 PR 中粘贴令牌。

安全、隐私与支持

• 请参阅 SECURITY.md，了解受支持的版本、漏洞报告、凭据处理要求和威胁模型说明。
• 请参阅 PRIVACY.md，了解可自托管环境中的数据处理、外部服务和公开 issue 的隐私指南。
• 请参阅 SUPPORT.md，了解支持渠道、支持范围和有用的错误报告背景信息。

开发

安装依赖：

corepack enable
corepack prepare [email protected] --activate
corepack pnpm install --frozen-lockfile

从头重新构建项目：

corepack pnpm build:clean

运行本地检查：

corepack pnpm verify

运行覆盖率检查：

corepack pnpm verify:coverage

运行选择启用的 Trello 实时冒烟测试：

TRELLO_LIVE_SMOKE=1 \
TRELLO_LIVE_SMOKE_BOARD_ID=your-disposable-board-id-or-short-link \
TRELLO_API_KEY=your-api-key \
TRELLO_TOKEN=your-token \
corepack pnpm smoke:live

在本地以监视模式运行：

TRELLO_API_KEY=your-key TRELLO_TOKEN=your-token corepack pnpm dev

在本地构建 Docker 镜像：

corepack pnpm docker:build

Codex Cloud 环境

Codex Cloud 任务会在 Agent 启动前运行设置脚本；当缓存容器在任务分支上恢复时，也可以运行可选的维护脚本。请在 Codex 环境设置中使用此仓库的脚本：

./scripts/codex/setup.sh

./scripts/codex/maintenance.sh

设置脚本会启用 Corepack、激活固定版本的 pnpm、在存在 pnpm-lock.yaml 时使用 --frozen-lockfile 安装依赖，并运行 pnpm typecheck。维护脚本会为缓存容器重复执行依赖同步和类型检查，避免分支更改导致使用过时的依赖。

故障排除

请从完整的故障排除指南开始，逐个边界诊断启动、stdio、HTTP 会话、Docker、Trello API、速率限制和附件故障。

服务已启动，但我的 MCP 客户端没有显示工具

• 确认客户端使用了正确的传输方式。
• 对于 stdio，请设置 TRANSPORT=stdio。
• 对于 HTTP，请将客户端指向 /mcp，而不是 /healthz 或 /readyz。
• 按照设置 MCP 客户端指南中针对相应客户端的重启或重新加载步骤操作。

Trello 提示凭据无效

• 在 MCP 客户端中运行 auth_whoami 和 auth_token_info 工具，确认已通过身份验证的成员，以及令牌的过期时间和权限。
• 确认令牌是使用同一个 Power-Up/API 密钥生成的。
• 如果令牌已被撤销，请重新生成。

Docker Compose 找不到 .env

• 将 .env.example 复制为 .env。
• 填写 TRELLO_API_KEY 和 TRELLO_TOKEN。
• 不要提交 .env。

我遇到了 Trello 速率限制

• 客户端会在每次 Trello 请求前使用令牌桶限流器。TRELLO_RATE_LIMIT_CAPACITY 控制每个令牌桶窗口内可以执行的请求数，TRELLO_RATE_LIMIT_REFILL_INTERVAL_MS 控制令牌桶的补充频率。
• 当 Trello 返回 HTTP 429 时，客户端会采用指数退避重试。TRELLO_RETRY_MAX_ATTEMPTS 控制请求尝试的总次数，TRELLO_RETRY_BASE_DELAY_MS 控制初始延迟和抖动范围，TRELLO_RETRY_MAX_DELAY_MS 限制每次重试等待的最长时间。
• 在 LOG_LEVEL=debug 时，令牌桶等待会记录为 trello rate limit wait。HTTP 429 重试会以 warn 级别记录为 trello request rate limited; retrying。这些日志包含安全元数据，例如方法、资源类型、资源 ID、尝试次数、最大尝试次数、状态代码和等待时长；不会包含 Trello 凭据、完整 URL、查询字符串或原始请求路径。
• 首先缩小提示词或工作流的范围：指定一个看板或列表，只请求所需字段，在适用时使用 limit、since、before 和 page，并避免要求大模型检查每张卡片；使用更小范围的搜索或筛选读取即可时，应优先采用这些方式。
• 如果大型工作流仍然经常需要等待，请谨慎调整配置。对于共用令牌或需要降低请求频率的自动化，可降低令牌桶容量：

TRELLO_RATE_LIMIT_CAPACITY=50
TRELLO_RATE_LIMIT_REFILL_INTERVAL_MS=10000

• 对于有意执行的大型用户触发工作流，可以在不增加请求令牌桶容量的情况下增加重试次数：

TRELLO_RETRY_MAX_ATTEMPTS=5
TRELLO_RETRY_BASE_DELAY_MS=250
TRELLO_RETRY_MAX_DELAY_MS=5000

• 除非了解 Trello 账户和令牌的实际工作负载，否则不要大幅提高 TRELLO_RATE_LIMIT_CAPACITY。容量过高可能导致范围较大的大模型驱动工作流更快触及 Trello 服务端的限制。
• 多次收到 429 响应后，请等待几分钟再重试工作流。

贡献

欢迎提交 PR。请让改动保持聚焦，为行为变更添加测试，并避免提交密钥或本地构建和测试输出。如果规范文档或公开工具数据发生变更，请运行 corepack pnpm docs:tools，并包含正式提交的生成文档镜像。

提交 PR 前，请运行：

corepack pnpm typecheck
corepack pnpm lint
corepack pnpm build
corepack pnpm test

许可证

MIT License。请参阅 LICENSE。