Favro

favro-mcp

一个使用 Go 编写的 Favro Model Context Protocol 服务。

它通过 stdio 使用 MCP，并将 Favro 的 REST API 封装为 86 个类型化工具。除了基本的 CRUD 功能外，它还提供了适用于自然语言操作的工作流工具——搜索、名称→ID 解析、精准修改描述——这样，大模型就能操作 Favro，而无需将速率限制额度耗费在往返查询上。每个修改类工具都支持 dry_run。

非官方。 与 Favro 无关联，也未获 Favro 认可。

要求： 从源代码构建需要 Go 1.27.3；还需要 Favro 账户和 API 令牌。版本历史请参阅 CHANGELOG.md。

安装

Claude Desktop 安装包

每个标记版本都会在 GitHub Releases 页面发布一个 favro-mcp_<version>.mcpb。打开它即可将服务安装到 Claude Desktop，并按提示填写所需的三个值——Favro 邮箱、API 令牌和组织 ID——无需手动编辑配置文件。

它还会询问配置文件中包含的另外两项设置。破坏性工具（enable_destructive）默认关闭，只有你主动启用才会开启；上传功能也默认关闭，直到你指定上传文件夹（upload_dir）。此服务不会在调用前征求任何人的同意。Claude Desktop 会逐个批准工具，而你设置为始终允许的工具之后会直接运行，因此除非需要使用相关工具，否则请保持 enable_destructive 关闭。

安装包包含 macOS 通用二进制文件、Windows amd64 二进制文件，以及由启动器在启动时选择的两种 Linux 架构版本。它已列入 checksums.txt 并受发布签名保护；请参阅验证下载文件。

Cowork 插件（推荐）

每个标记版本都会在 GitHub Releases 页面发布一个包含多种架构的 favro-mcp.plugin 压缩包。该压缩包包含适用于 darwin-amd64、darwin-arm64、linux-amd64、linux-arm64 和 windows-amd64 的二进制文件。在 macOS 和 Linux 上，启动器垫片会在运行时选择合适的版本；在 Windows 上，.cmd 垫片会运行 windows-amd64 二进制文件，Windows on arm64（windows-arm64）则通过模拟运行该文件。

1. 从发布页面下载 favro-mcp.plugin。
2. 将其安装到你的 Cowork 配置文件中（拖放安装，或按照 Cowork 的插件安装流程操作）。
3. 完成身份验证（见下文身份验证）。
4. 重启 Cowork——favro MCP 服务将会出现，且所有工具均已注册。

捆绑的 .mcp.json 指向 ${CLAUDE_PLUGIN_ROOT}/bin/favro-mcp，因此安装位置可变，无需修改主机路径。

独立二进制文件

适用于非 Cowork 主机（通过原始 .mcp.json 使用 Claude Code、MCP Inspector、自定义集成）：

1. 从发布页面下载对应的 favro-mcp_<version>_<os>_<arch>.tar.gz（Windows 上为 .zip）。
2. 解压并将 favro-mcp 二进制文件放到 $PATH 中的某个位置（或记下它的绝对路径）。
3. 完成身份验证。
4. 在 MCP 主机配置中指向该二进制文件——请参阅下文的 MCP 主机配置。

从源代码构建

git clone https://github.com/mmedum/favro-mcp
cd favro-mcp
make build       # → bin/favro-mcp

需要 Go 1.27.3，即 go.mod 中声明的版本。使用默认的 GOTOOLCHAIN=auto 时，较旧的工具链会按需下载该版本；使用 GOTOOLCHAIN=local 时，构建会直接失败，而不会降级。

验证下载文件

每个版本都包含 checksums.txt、每个归档文件各自的 SBOM、针对校验和文件的无密钥 cosign 签名，以及由 GitHub 证明的构建来源证明。.mcpb 捆绑包与归档文件一同列在 checksums.txt 中，因此一个签名即可覆盖所有内容。

# 1. The file is what the release says it is.
sha256sum -c checksums.txt --ignore-missing

# 2. The checksum file came from this repository's release workflow.
cosign verify-blob checksums.txt \
  --bundle checksums.txt.bundle \
  --certificate-identity-regexp '^https://github\.com/mmedum/favro-mcp/' \
  --certificate-oidc-issuer https://token.actions.githubusercontent.com

# 3. Which workflow, at which commit, built a given artifact.
gh attestation verify favro-mcp_<version>_<os>_<arch>.tar.gz --repo mmedum/favro-mcp

构建可复现：使用 -trimpath 和提交自身的时间戳，因此重新构建某个标签会得到字节完全相同的归档文件。

身份验证

该服务使用 Favro 的 HTTP Basic Auth（用户邮箱 + API 令牌），并在启动时限定为一个 Favro 组织。工具不会接受 organization_id——通过环境变量或密钥环传入一次，此后无需再管。

API 令牌与用户绑定——用于团队安装时，请从专用的服务型 Favro 用户生成令牌，并授予所需的最低权限，而不要使用个人帐户生成。

凭据解析

按顺序检查两个来源；第一个能提供完整 (email, token, organization_id) 三元组的来源会胜出：

1. 环境变量——FAVRO_USER_EMAIL、FAVRO_API_TOKEN、FAVRO_ORGANIZATION_ID。
2. 操作系统密钥环——通过 favro-mcp auth login 填充一次（跨平台：macOS Keychain、Windows Credential Manager、Linux Secret Service）。

还有四个变量会改变服务的运行方式，而非运行身份：

变量	效果
FAVRO_LOG_LEVEL	debug / info（默认值）/ warn / error。日志输出到 stderr；stdout 仅承载 MCP 协议流。
FAVRO_MCP_SKIP_VALIDATE	设为 true 可跳过启动时向 Favro 验证凭据的调用。用于离线测试；此时服务会在首次实际工具调用时失败，而不是在启动时失败。false、0 以及任何无法识别为 true 的值都会保留验证检查。
FAVRO_ENABLE_DESTRUCTIVE	设为 true 可注册具有破坏性的工具：删除工具和 favro_widen_collection_sharing。默认关闭；所谓“关闭”是指它们不会出现在 tools/list 中，而非受到防护——处于自动批准模式的宿主会在不提示的情况下运行工具，因此不注册才是唯一的保障。任何无法识别为 true 的值都会使这些工具保持关闭。每次调用还必须传入 confirm: true。
FAVRO_UPLOAD_DIR	上传工具读取文件的唯一目录，必须使用绝对路径。未设置时，不会注册这些工具。不会读取该目录之外的任何内容，也会拒绝指向目录外部的链接。

每个变量（包括凭据）读取时都会去除其值两端的空格；如果值只有空格，则视为未设置。

FAVRO_REQUIRE_PROMPT 已移除。若将其设为任何非 false 值，服务会拒绝启动；请取消设置。FAVRO_INTERACTION_HINT 也已移除：若将其设为 false，该值会被忽略并显示警告，带标记的工具仍会保留其标记。

批准调用

每次调用都由 MCP 客户端批准；服务端不会自行询问你。 claude.ai 和 Codex 会提示确认带有 destructiveHint 标记的破坏性工具，而 VS Code 会提示确认每个会写入数据的工具。

在 Claude Code 中，无论规则如何设置，每次调用以下五个工具时都会询问： favro_delete_tag、favro_delete_group、favro_delete_widget 和 favro_delete_collection，这些工具造成的损失会波及被删除对象以外的内容；以及 favro_widen_collection_sharing，它会将集合开放给整个组织或任何持有链接的人。在无法显示提示的场景中，例如 claude -p，Claude Code 会拒绝执行这些工具。对于其余工具，请在设置中的 permissions.ask 下逐一列出要批准的调用，并用你为服务端指定的名称代替 favro。例如，以下会共享、发布、发送文件或删除内容的写入操作：

{
  "permissions": {
    "ask": [
      "mcp__favro__favro_create_collection", "mcp__favro__favro_update_collection",
      "mcp__favro__favro_widen_collection_sharing",
      "mcp__favro__favro_create_group", "mcp__favro__favro_update_group",
      "mcp__favro__favro_upload_attachment", "mcp__favro__favro_upload_comment_attachment",
      "mcp__favro__favro_delete_tag", "mcp__favro__favro_delete_group",
      "mcp__favro__favro_delete_widget", "mcp__favro__favro_delete_collection",
      "mcp__favro__favro_delete_column", "mcp__favro__favro_delete_card",
      "mcp__favro__favro_delete_comment", "mcp__favro__favro_delete_task",
      "mcp__favro__favro_delete_tasklist", "mcp__favro__favro_delete_webhook",
      "mcp__favro__favro_remove_attachment", "mcp__favro__favro_replace_dependencies",
      "mcp__favro__favro_delete_dependency", "mcp__favro__favro_delete_all_dependencies"
    ]
  }
}

客户端无论执行什么操作，都有以下约束：

• 仅在请求时使用破坏性工具。 只有设置 FAVRO_ENABLE_DESTRUCTIVE=true 后，这些工具才会启用，并且每次调用都必须通过 confirm: true；dry_run: true 可在不确认的情况下预览操作。
• 共享范围仅限组织内部。 常规的集合、组和组件写入只会与组织成员（以 userId 指定）以及成员组共享。系统会拒绝通过电子邮件发送邀请、添加新的管理员、邀请组织外人员、包含组织外人员的组、将访客设为组件所有者或编辑者，以及公开集合或面向全组织开放集合的请求。 favro_widen_collection_sharing 会开放一个集合，并且会同时接收集合名称和 ID，以便提示中显示具体是哪个集合。
• 不会因省略参数而扩大删除范围。 favro_delete_widget 必须接收 collection_id 或 everywhere: true；两者都未提供时会拒绝调用。

auth 子命令

favro-mcp auth login       # interactive: masked token input, writes to keyring
favro-mcp auth status      # show user/org (token never printed)
favro-mcp auth logout      # delete keyring entries
favro-mcp auth which       # print active credential source: env or keyring
favro-mcp doctor           # check credentials, org binding and API reachability
favro-mcp doctor --show-ids  # the same, unredacted, for your own screen
favro-mcp --version        # print version + commit
favro-mcp --dry-run        # process-wide override: forces all writes into dry-run

favro-mcp auth login 是使用密钥环路径的一次性设置命令。重新运行即可轮换令牌。

当某项功能无法正常运行时，首先运行 favro-mcp doctor。它会报告构建版本、凭据的来源、Favro 是否接受这些凭据，以及组织 ID 是否对应令牌实际可访问的组织——否则就会出现所有工具都返回 not_found 的情况。输出会将 ID 和地址替换为稳定的占位符，便于粘贴到问题报告中；--show-ids 会在你的屏幕上显示实际值，并注明这一点。

MCP 主机配置

安装好二进制文件或插件并存储凭据后，在 MCP 主机配置中注册服务端。

默认方式（密钥环路径，配置中不含任何密钥）：

{
  "mcpServers": {
    "favro": { "command": "/path/to/favro-mcp" }
  }
}

无头环境 / CI（环境变量） — 从 Shell 传递密钥，不要直接写入：

{
  "mcpServers": {
    "favro": {
      "command": "/path/to/favro-mcp",
      "env": {
        "FAVRO_USER_EMAIL": "${FAVRO_USER_EMAIL}",
        "FAVRO_API_TOKEN": "${FAVRO_API_TOKEN}",
        "FAVRO_ORGANIZATION_ID": "${FAVRO_ORGANIZATION_ID}"
      }
    }
  }
}

Cowork 插件自带 .mcp.json，其中的路径指向 ${CLAUDE_PLUGIN_ROOT}/bin/favro-mcp，因此通过该路径安装时无需手动配置。

速率限制

Favro 按组织实施基于套餐等级的速率限制（Lite 约为 100 次/小时，Standard 约为 1000 次/小时，Enterprise 约为 10000 次/小时）。行为异常的 Agent 可能耗尽整个组织的配额。服务端会在内存中缓存解析查询结果（标签、用户、组件、列），并且每个列表 / 解析工具都支持 force_refresh，以便在需要时清除缓存。列表工具不会自动汇总分页结果——每次获取下一页都需要显式调用 next_page，以便大模型能够提前停止。

试运行

每个会修改数据的工具都接受 dry_run: true，并会返回拟发送的 HTTP 请求（方法、URL、请求体）以及状态差异预测，而不会联系 Favro。读取工具不接受 dry_run。

对于沙盒或自主运行前的测试，二进制文件上的 --dry-run 会强制整个进程进入试运行模式，不受每次调用输入的影响。

工具

86 个工具覆盖了 Favro 的所有 REST 资源，另有专为自然语言使用设计的工作流工具。完整参考请参阅 docs/TOOLS.md。

建议先了解以下工具：

工具	功能
favro_search_cards	对卡片名称和描述进行全文搜索。可限定范围为某个小组件或集合。
favro_get_card_full	获取一张卡片，并将所有 ID 解析为名称，节省 4–7 次后续调用。
favro_resolve_*	将名称转换为 ID，适用于标签、用户、集合、小组件、列、自定义字段和群组。
favro_append_card_description	精准编辑描述，并返回统一差异。
favro_ping	本地诊断：版本、绑定的组织、凭据来源。绝不会联系 Favro。

故障排除

先运行 favro-mcp doctor——它会直接解答下表中的大多数问题，而且其输出可安全地粘贴到 issue 中。

症状	诊断与修复
所有工具都返回 [not_found]，但凭据已通过验证	FAVRO_ORGANIZATION_ID 指定的组织不在此令牌可访问的范围内。favro-mcp doctor 会将其报告为组织绑定失败；favro-mcp doctor --show-ids 会列出此令牌可以访问的 ID。
启动时提示 authentication failed — check FAVRO_USER_EMAIL and FAVRO_API_TOKEN env vars	可能是未配置凭据，也可能是令牌已撤销或轮换。运行 favro-mcp auth which 确认服务读取的是哪个来源，然后重新运行 favro-mcp auth login（密钥环路径），或更新环境变量。
启动时提示 FAVRO_ORGANIZATION_ID is required	此服务按设计只支持单个组织——启动前必须知道每个请求要限定到哪个组织。设置 FAVRO_ORGANIZATION_ID（或在 auth login 中包含该值），然后重启。
HTTP 429 / rate limit exceeded	已触及 Favro 的组织级速率限制。客户端会遵循 Retry-After 重试一次（上限为 30 秒），随后返回包含 retry_after_seconds 的类型化错误。使用 favro_rate_limit_status 查看最近的 X-RateLimit-* 标头，无需额外发起调用。
next_page 一直返回非 null 值	列表工具不会自动聚合结果。每次后续调用都必须包含 page 和相同的 request_id（Favro 通过 X-Favro-Backend-Identifier 路由分页读取）；某些工具还需要重新发送原始筛选条件。
decodeJSONLenient 报错，内容为 content-type: text/html, body-prefix: "<p>It looks like…"	你访问了 Favro 文档所列接口之外的端点——Favro 返回了 SPA 回退页面，而不是 404。错误中包含状态码、内容类型和正文前缀，便于你通过一次往返完成诊断。
自定义字段写入返回 200，但值没有变化	有两个已知原因。第一，该字段可能未在对应组件上启用——组织全局自定义字段仍需在 Favro UI 中为每个组件单独启用；写入组件不包含的字段会被接受并忽略。第二，Favro 会静默忽略未知的正文参数，因此错误的字段类型结构看起来就像成功；favro_set_card_custom_field 会按 Favro REST 文档指定的结构发送数据，但这些结构尚未全部在实际租户上验证。使用 favro_get_card_full 重新读取卡片以确认。
写入成功后，工具描述中的数据仍是旧的	所有缓存失效操作都按组织和资源类型限定；如果写入成功但下一次读取仍显示旧数据，请在列表/解析工具中传入 force_refresh: true。
Linux 启动器无法从插件运行	启动器是 bash 脚本。如果你的 shell 无法执行它，请将 .mcp.json 直接指向 ${CLAUDE_PLUGIN_ROOT}/bin/linux-amd64/favro-mcp（或 linux-arm64）。
Windows	随附的 bin/favro-mcp.cmd 垫片会执行 bin\windows-amd64\favro-mcp.exe。Windows 主机通过 PATHEXT 会自动将 ${CLAUDE_PLUGIN_ROOT}/bin/favro-mcp 解析为 .cmd，因此 MCP 主机配置中的标准 .mcp.json 配置可直接使用。如果你的主机不遵循 PATHEXT，请将 command 指向 ${CLAUDE_PLUGIN_ROOT}/bin/favro-mcp.cmd（或直接指向 bin/windows-amd64/favro-mcp.exe）。

文档

docs/TOOLS.md	每个工具、其输入及返回内容。
docs/configuration.md	每项设置、相关命令及启动时的行为。
docs/security.md	信任边界、日志记录的内容，以及各项限制的作用。
docs/development.md	质量门禁、测试规范及发布流程。
docs/architecture.md	设计、已确定的约束、证据记录及阶段计划。
SECURITY.md	如何报告漏洞。

开发

请参阅 docs/development.md，了解质量门禁和测试规范；参阅 CONTRIBUTING.md，了解如何设置环境并提交拉取请求。

许可证

Apache 2.0 — 请参阅 LICENSE 和 NOTICE。