focalboard-mcp

An MCP server for Focalboard, the self-hosted Trello/Notion/Asana alternative. Lets an MCP client (Claude Code, Claude Desktop, etc.) read and manage boards and cards on a self-hosted Focalboard instance.

Property values are matched by human-readable name and label (e.g. "Status": "Done"), not by Focalboard's internal property/option ids, so the model doesn't need to know your board's schema up front. Unknown property/option names get a "did you mean" suggestion instead of a bare error.

Why another Focalboard MCP server?

A few already exist. This one is built directly against Focalboard's server source (server/api/*.go, server/model/*.go, and the webapp's block components) rather than reverse-engineered from another wrapper, and goes further on feature depth: comments, checklists (with the contentOrder bookkeeping Focalboard's UI needs to actually show them), image attachments returned as real MCP image content, an instance-wide search, and a fuzzy find_cards.

Focalboard quirks this handles (found by reading the source, not guessing)

• Cards have a dedicated, flat-properties API (/boards/{id}/cards, PATCH /cards/{id}) distinct from the generic blocks API.
• Creating a block via the generic blocks API requires client-supplied non-zero createAt/updateAt timestamps, or the server 400s.
• Login itself needs the X-Requested-With CSRF header, not just authenticated requests.
• Checklist items only render in Focalboard's UI if you also append them to the card's contentOrder.
• A card's actual body text lives in separate text content blocks, not on the card itself.
• Image attachments come back from Focalboard's file endpoint as application/octet-stream regardless of the real file type, so get_card derives the MIME type from the filename extension instead of trusting that header.

Scope

Covers boards, cards, comments, checklists, and image attachments — enough for day-to-day project planning. It does not cover board/template creation, member management, or sharing/permissions; PRs welcome if you need those.

Compatibility

Targets standalone Focalboard (Personal Server / Team Edition) using its normal /api/v2 username+password login. Two deployment modes reject that login entirely (confirmed in server/api/auth.go) and won't work with this server:

• Mattermost plugin mode — Focalboard running as a Boards plugin inside Mattermost authenticates through Mattermost instead; the standalone login endpoint is disabled.
• Single-user mode — instances configured with a fixed FOCALBOARD_SINGLE_USER_TOKEN also reject username/ password login.

If your instance runs one of those, pnpm smoke will fail fast with a clear error instead of doing anything destructive.

Tools

Tool	Description
list_teams	List teams visible to the authenticated user
list_boards	List boards for a team (teamId optional if the instance has only one team)
get_board	Get a board's properties (columns) and their options
search_boards	Search board titles across the whole instance
list_cards	List cards on a board, with properties resolved to names/labels
find_cards	Fuzzy-search card titles on a board
get_card	Get a card by id, including properties, body content, comments, checklist items, and any attached images
create_cards	Create one or more cards on a board
update_card	Update a card's title and/or properties
delete_card	Delete a card
add_comment	Add a comment to a card
add_checklist_item	Add a checklist item to a card
set_checklist_item	Check/uncheck a checklist item

Getting Started

This isn't published to npm (yet) — you clone and build it locally, point it at your Focalboard instance, and register it with your MCP client. Requires Node.js >= 20.

1. Clone and build

git clone https://github.com/giordano137/focalboard-mcp.git
cd focalboard-mcp
pnpm install
pnpm build

This produces dist/index.js, the actual server your MCP client will run.

2. Configure credentials

cp .env.example .env

Edit .env with your instance's details:

FOCALBOARD_HOST=https://your-focalboard-instance.example
FOCALBOARD_USERNAME=your-username
FOCALBOARD_PASSWORD=your-password

.env is gitignored — it never gets committed. The server authenticates via Focalboard's session login (POST /api/v2/login) and re-authenticates automatically if the session expires; see Security for why credentials belong in this file and not on the command line.

Sanity-check the connection before registering anything (read-only, touches nothing):

pnpm smoke

3. Register with your MCP client

Claude Code, registered once, available in every session (-s user) — not tied to this repo's directory:

claude mcp add focalboard -s user -- \
  node --env-file=/absolute/path/to/focalboard-mcp/.env /absolute/path/to/focalboard-mcp/dist/index.js

New registrations need a fresh Claude Code session to be picked up — an already-running session won't see it.

Claude Desktop (or any other MCP client that reads a mcpServers JSON config): add this to claude_desktop_config.json (macOS: ~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "focalboard": {
      "command": "node",
      "args": [
        "--env-file=/absolute/path/to/focalboard-mcp/.env",
        "/absolute/path/to/focalboard-mcp/dist/index.js"
      ]
    }
  }
}

Then restart the client. Either way: use --env-file pointing at your .env, not -e/--env flags with the credentials inline — those end up in plaintext in the client's own config file and shell history.

4. Use it

Once registered, there's nothing to invoke manually — just talk to your MCP client and it picks the right tools. A few examples of what that looks like:

"What boards do I have on Focalboard?"

Calls list_teams (skipped automatically if you only have one team), then list_boards.

"Show me everything that isn't Done on the Kaizen board"

Calls get_board to see the Status property's valid options, then list_cards and filters by the resolved Status value — no need to know Focalboard's internal property/option ids.

"Create a card 'Fix login bug' with Status Todo and Priority High"

Calls create_cards with properties: {"Status": "Todo", "Priority": "High"} — plain names and labels, matched case-insensitively. A typo like "Statuss" or "Todoo" comes back with a "did you mean" suggestion instead of a bare error.

"What's in the 'Redesign' card, including any screenshots?"

Calls get_card, which returns properties, body text, comments, and checklist items as JSON, plus any attached images inline as actual image content the model can see — not just a filename.

"Mark 'write tests' as done on that card and add a comment that it's ready for review"

Calls set_checklist_item and add_comment.

Development

pnpm dev         # run from source with tsx
pnpm typecheck
pnpm lint
pnpm test        # watch mode
pnpm test:run    # single run
pnpm smoke       # read-only sanity check against your real instance
pnpm backup      # export all teams/boards/cards to backups/*.json (gitignored)
pnpm write-test  # create/update/comment/checklist/delete a throwaway card on a test board, end to end

CI runs typecheck/lint/test/build on Node 20 and 22 for every push and PR (.github/workflows/ci.yml).

Contributing

Issues and PRs welcome — see Scope for what's not covered yet. Keep changes covered by tests; pnpm smoke, pnpm write-test, and pnpm backup are also useful for verifying against a real instance before opening a PR.

Security

Credentials are only ever read from environment variables (see .env.example) — never pass them as CLI flags to an MCP client, since those tend to land in the client's own config file and shell history in plaintext. There's currently no supported way to use a scoped, long-lived personal access token instead of a full username/password session login. Please report security issues via GitHub's private vulnerability reporting rather than a public issue.

License

MIT