favro-mcp

An MCP server that gives your AI assistant read access to Favro — collections, boards, cards, comments and checklists.

Read-only by design. Every one of the 14 tools issues a GET and nothing else. There is no code path in this package that can create, change, archive or delete anything in your Favro account — a test asserts it on every commit. You are handing over an API token, so that guarantee is the point.

Install

Nothing to install. Point your MCP client at npx:

{
  "mcpServers": {
    "favro": {
      "command": "npx",
      "args": ["-y", "favro-mcp"],
      "env": {
        "FAVRO_EMAIL": "you@example.com",
        "FAVRO_API_TOKEN": "your-api-token",
        "FAVRO_ORGANIZATION_ID": ""
      }
    }
  }
}

Requires Node 18 or newer.

Getting a Favro API token

In Favro: profile menu → My profile → API tokens → Create new token. The token pairs with the email address you sign in with; both are needed.

FAVRO_ORGANIZATION_ID is optional. Leave it empty and ask your assistant to run list-organizations — it will return the ids you have access to, and you can either paste one into the config or let the assistant pass it per call.

Per-client setup

claude mcp add favro --env FAVRO_EMAIL=you@example.com --env FAVRO_API_TOKEN=your-api-token -- npx -y favro-mcp

Or add the JSON block above to .mcp.json in your project root.

Edit claude_desktop_config.json:

• macOS — ~/Library/Application Support/Claude/claude_desktop_config.json

• Windows — %APPDATA%\Claude\claude_desktop_config.json

Paste the JSON block above, then fully quit and reopen Claude Desktop — reloading the window is not enough.

Edit ~/.cursor/mcp.json (global) or .cursor/mcp.json (per project) and paste the JSON block above.

Add to .vscode/mcp.json, using servers rather than mcpServers:

{
  "servers": {
    "favro": {
      "command": "npx",
      "args": ["-y", "favro-mcp"],
      "env": {
        "FAVRO_EMAIL": "you@example.com",
        "FAVRO_API_TOKEN": "your-api-token"
      }
    }
  }
}

Related MCP server: jama-mcp-server

Tools

Every tool also accepts an optional organizationId to override the configured default.

Configuration

Things worth knowing

The API's vocabulary differs from the UI

Cards have two ids

• cardId identifies one card on one board. get-card takes this.

• cardCommonId identifies the card across every board it appears on. The comment and checklist tools take this.

Both come back from list-cards and get-card.

A typical path through the hierarchy

list-organizations           (only when FAVRO_ORGANIZATION_ID is unset)
  → list-collections         find the collection
    → list-boards            boards in that collection
      → get-board            its columns and lanes, in one call
        → list-cards         cards on the board or in a column
          → get-card         full detail on one card
            → list-card-comments / list-card-tasklists / list-card-tasks

Pagination

Listings return up to 100 entities. When more remain, the response carries a cursor:

"pagination": {
  "page": 0,
  "pages": 3,
  "requestId": "...",
  "backendId": "...",
  "next_page": { "page": 1, "requestId": "...", "backendId": "..." }
}

Call the same tool again passing page, requestId and backendId exactly as given. All three are required — Favro routes follow-up pages to the same backend server, and the backendId is what gets them there.

search-cards is a local filter, not a search endpoint

Favro's API has no card search. search-cards reads cards from a board or collection and filters them by case-insensitive substring on name and description. It reads up to maxPages pages (default 3, maximum 10), each costing one API call, and reports what it covered:

"scan": {
  "cards_scanned": 250,
  "matches_found": 4,
  "pages_read": 3,
  "pages_available": 5,
  "complete": false,
  "note": "Only 3 of 5 pages were searched. Raise maxPages..."
}

When complete is false, narrow the scope or raise maxPages rather than treating the result as exhaustive.

Rate limits and caching

Favro's hourly budget is low and plan-dependent — 100/hour on Trial up to 10,000/hour on Enterprise, with list-organizations and the user tools sharing a separate 50/hour budget. Every response carries a rate_limit block showing what is left.

To conserve calls, organizations, users, collections, boards and columns are cached for FAVRO_CACHE_TTL seconds. Cached responses are marked "cached": true. Cards, comments and checklists are never cached, so they are always current.

Not covered

Tags, custom field definitions, groups and webhooks are not exposed, and nothing writes to Favro. Open an issue if you need something added.

Development

npm install
npm test
npm run build

Inspect the server interactively against your real account:

FAVRO_EMAIL=you@example.com FAVRO_API_TOKEN=your-token npx @modelcontextprotocol/inspector node dist/index.js

License

MIT