Focalboard

You can manage Focalboard boards and cards through an MCP server that connects to your Focalboard instance. This MCP enables Claude and other MCP-compatible clients to list boards, view details, create and update cards, manage descriptions with Markdown, and move cards between columns using friendly property names. It handles authentication automatically and keeps interactions smooth across sessions.

How to use

Connect to the MCP server from your MCP client and start by listing your boards to understand what you have available. Retrieve board details to see the columns and properties you can use, then create or update cards by referencing board and card IDs along with human-friendly property names like Status or Priority.

Common workflows you can perform include creating a new card with a title and optional description, updating card properties to move it between columns, adding or editing descriptions with Markdown, and fetching card content blocks to view all descriptions and text blocks currently attached to a card.

How to install

Prerequisites: you need Node.js and npm installed on your machine. You also interact with Claude or another MCP client to configure and start the server.

Option 1: Using Claude CLI (Recommended) — run the following to add the focalboard MCP server and start it using stdio transport.

claude mcp add --transport stdio focalboard \
  --env FOCALBOARD_HOST=https://your-focalboard-instance.com \
  --env FOCALBOARD_USERNAME=your-username \
  --env FOCALBOARD_PASSWORD=your-password \
  -- npx -y github:gmjuhasz/focalboard-mcp-server

If you have cloned the project locally, install dependencies, build, and run the server with the following commands.

cd /path/to/focalboard-mcp-server
npm install
npm run build

claude mcp add --transport stdio focalboard \
  --env FOCALBOARD_HOST=https://your-focalboard-instance.com \
  --env FOCALBOARD_USERNAME=your-username \
  --env FOCALBOARD_PASSWORD=your-password \
  -- node /absolute/path/to/focalboard-mcp-server/build/index.js

Option 2: Manual installation

Follow these steps to set up the MCP server manually.

# 1. Clone or download this project
# 2. Install dependencies
npm install
# 3. Build the project
npm run build
# 4. Add to Claude Desktop configuration (example for macOS)
# MacOS path example
# 5. Restart Claude Desktop

Configuration

Environment variables you use to connect to Focalboard are required for authentication and host details.

{
  "mcpServers": {
    "focalboard": {
      "command": "node",
      "args": ["/absolute/path/to/focalboard-mcp-server/build/index.js"],
      "env": {
        "FOCALBOARD_HOST": "https://your-focalboard-instance.com",
        "FOCALBOARD_USERNAME": "your-username",
        "FOCALBOARD_PASSWORD": "your-password"
      }
    }
  }
}

Authentication and usage notes

The MCP server automatically handles authentication with your Focalboard credentials. It logs in on first use, stores a session token, re-authenticates if needed, and uses the token for subsequent requests.

When updating a card’s properties, you can use friendly property names (for example, Status or Priority). The server resolves these names to internal IDs so you can write commands using human-friendly terms rather than cryptic IDs.

Working with descriptions and content

Descriptions support full Markdown, including bold, italics, lists, code blocks, headers, and links. You can add or update a card description and retrieve all content blocks to see current descriptions and text blocks.

Notes on moving cards between columns

To move a card between columns, update the property that defines the column (for example, set Status to a different option like "In Progress" or "Done"). The server translates the friendly value to the correct internal option ID automatically.

Troubleshooting

Authentication errors usually indicate a host URL issue or incorrect credentials. Ensure your Focalboard host starts with https:// and that your username and password are correct. If a board or card cannot be found, list boards and fetch cards to confirm IDs. Property names are case-insensitive but must match the defined names exactly for the board.

Examples and workflows

Common workflows include listing boards, viewing a board’s details, creating a card with a title and optional description, updating a card’s status, and retrieving card content blocks to inspect descriptions. Use human-readable property names to simplify interactions.

Development

The MCP server is built with TypeScript and can be built and run via standard npm scripts. Build artifacts produce a single entry point used by the stdio runtime.

License

MIT license

Available tools

list_boards

List all boards for a team, optionally filtering by teamId.

get_board

Retrieve detailed information about a specific board, including its columns and properties.

search_boards

Search boards by name or keyword within a team.

create_card

Create a new card in a board with an optional description and initial properties.

get_cards

List all cards in a board with optional pagination.

get_card

Get detailed information about a specific card.

update_card

Update a card’s properties, title, and/or description, and support moving between columns via property updates.

delete_card

Permanently remove a card from a board.

add_card_description

Add or update the description of an existing card using Markdown.

get_card_content

Retrieve all content blocks for a card, including descriptions and text blocks.