Favro

favro-mcp

A Model Context Protocol server for Favro, written in Go.

It speaks MCP over stdio and exposes Favro's REST API as 86 typed tools. Beyond plain CRUD, it ships workflow tools built for natural-language use — search, name→ID resolution, surgical description edits — so an LLM can act on Favro without spending its rate-limit budget on lookup round-trips. Every mutating tool supports dry_run.

Unofficial. Not affiliated with or endorsed by Favro.

Requirements: Go 1.27.3 to build from source; a Favro account with an API token. See CHANGELOG.md for release history.

Installation

Claude Desktop bundle

Each tagged release publishes a favro-mcp_<version>.mcpb on the GitHub Releases page. Opening it installs the server into Claude Desktop and prompts for the three values it needs — your Favro email, an API token, and the organization id — so there is no config file to hand-edit.

The bundle carries a macOS universal binary, a Windows amd64 binary, and both Linux architectures behind a launcher that picks at startup. It is listed in checksums.txt and covered by the release signature; see Verifying a download.

Cowork plugin (recommended)

Each tagged release publishes a single multi-arch favro-mcp.plugin zip on the GitHub Releases page. The bundle contains binaries for darwin amd64/arm64 and linux amd64/arm64, plus a launcher shim that picks the right one at runtime.

1. Download favro-mcp.plugin from the release.
2. Install it into your Cowork profile (drag-and-drop, or follow Cowork's plugin install flow).
3. Authenticate (see Authentication below).
4. Restart Cowork — the favro MCP server will appear with all tools registered.

The bundled .mcp.json points at ${CLAUDE_PLUGIN_ROOT}/bin/favro-mcp so the install is relocatable; no host paths to edit.

Standalone binary

For non-Cowork hosts (Claude Code via raw .mcp.json, MCP Inspector, custom integrations):

1. Download the matching favro-mcp_<version>_<os>_<arch>.tar.gz (or .zip on Windows) from the release.
2. Extract and place the favro-mcp binary somewhere on $PATH (or note its absolute path).
3. Authenticate.
4. Point your MCP host's config at the binary — see MCP host configuration below.

From source

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

Requires Go 1.27.3, the version go.mod declares. Under the default GOTOOLCHAIN=auto an older toolchain downloads it on demand; under GOTOOLCHAIN=local the build fails instead of downgrading.

Verifying a download

Every release carries checksums.txt, an SBOM per archive, a keyless cosign signature over the checksum file, and build provenance attested by GitHub. The .mcpb bundle is in checksums.txt with the archives, so one signature covers all of it.

# 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

Builds are reproducible: -trimpath plus the commit's own timestamp, so rebuilding a tag gives byte-identical archives.

Authentication

The server uses Favro's HTTP Basic Auth (user email + API token), scoped to one Favro organization at startup. Tools never accept organization_id — pass it once via env var or keyring and forget about it.

API tokens are user-scoped — for team installs, generate the token from a dedicated service-style Favro user with the minimum permissions you need, not from a personal account.

Credential resolution

Two sources, checked in order; the first one that produces a complete (email, token, organization_id) triple wins:

1. Environment variables — FAVRO_USER_EMAIL, FAVRO_API_TOKEN, FAVRO_ORGANIZATION_ID.
2. OS keyring — populated once via favro-mcp auth login (cross-platform: macOS Keychain, Windows Credential Manager, Linux Secret Service).

Four more variables change how the server runs rather than who it runs as:

FAVRO_REQUIRE_PROMPT is removed. Set to anything but false, the server refuses to start; unset it. FAVRO_INTERACTION_HINT is removed too: set to false, it is ignored with a warning, and the marked tools keep their mark.

Approving calls

Your MCP client approves each call; the server does not ask you itself. claude.ai and Codex prompt for the destructive tools, which are marked destructiveHint, and VS Code prompts for every tool that writes.

In Claude Code, five tools ask on every call whatever your rules say: favro_delete_tag, favro_delete_group, favro_delete_widget and favro_delete_collection, whose loss reaches past the one thing deleted, and favro_widen_collection_sharing, which opens a collection to the whole organization or to anyone with its link. Where no prompt can be shown, as in claude -p, Claude Code refuses them. For the rest, list the calls you want to approve one by one under permissions.ask in your settings, with the name you gave the server in place of favro. For example, the writes that share, publish, send a file or delete:

{
  "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"
    ]
  }
}

What holds whatever the client does:

• Destructive tools only on request. They exist only with FAVRO_ENABLE_DESTRUCTIVE=true, and each call must pass confirm: true; dry_run: true previews without it.
• Sharing stays inside the organization. The ordinary collection, group and widget writes share only with members of the organization, named by userId, and with groups of members. An invitation by email, a new admin, someone outside the organization, a group that holds someone outside it, guests as a widget's owners or editors, and a public or organization-wide collection are refused. favro_widen_collection_sharing opens a collection, and takes the collection's name as well as its id, so the prompt shows which one.
• No wider delete by omission. favro_delete_widget takes collection_id or everywhere: true, and refuses a call with neither.

auth subcommands

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 is the one-shot setup for the keyring path. Re-run it to rotate the token.

favro-mcp doctor is the first thing to run when something does not work. It reports the build, which source the credentials came from, whether Favro accepts them, and whether the organization id names one the token can actually see — the failure that otherwise shows up as every tool returning not_found. Its output replaces ids and addresses with stable placeholders so it can be pasted into an issue; --show-ids prints the real values for your own screen, and says so.

MCP host configuration

After the binary or plugin is in place and credentials are stored, register the server in your MCP host config.

Default (keyring path, zero secrets in config):

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

Headless / CI (env vars) — passes secrets through from the shell, never literal:

{
  "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}"
      }
    }
  }
}

The Cowork plugin ships its own .mcp.json pointing at ${CLAUDE_PLUGIN_ROOT}/bin/favro-mcp, so for that install path no manual config is needed.

Rate limits

Favro enforces tier-based rate limits per organization (Lite ~100/hr, Standard ~1000/hr, Enterprise ~10000/hr). A misbehaving agent can exhaust the quota for everyone in your org. The server caches resolution lookups (tags, users, widgets, columns) in-memory and supports force_refresh on every list/resolve tool to bust the cache when needed. List tools never auto-aggregate pages — each next_page requires an explicit follow-up call so the LLM can stop early.

Dry-run

Every mutating tool accepts dry_run: true and returns the would-be HTTP request (method, URL, body) plus a state-diff prediction without contacting Favro. Read tools never accept dry_run.

For sandboxed or pre-autonomy testing, --dry-run on the binary forces dry-run mode process-wide regardless of per-call input.

Tools

86 tools covering every Favro REST resource, plus workflow tools built for natural-language use. See docs/TOOLS.md for the full reference.

The ones worth knowing first:

Troubleshooting

Run favro-mcp doctor first — it answers most of the rows below directly, and its output is safe to paste into an issue.

Documentation

Development

See docs/development.md for the gates and the test conventions, and CONTRIBUTING.md for how to get set up and open a pull request.

License

Apache 2.0 — see LICENSE and NOTICE.