Focalboard MCP Server

A Model Context Protocol (MCP) server for Focalboard, enabling task and board management through Claude and other MCP-compatible clients.

Features

• Board Management: List, search, and view board details

• Card Operations: Create, read, update, and delete cards/tasks

• Description Support: Add and update card descriptions with full markdown support

• Content Management: View and manage card content blocks (descriptions, text, etc.)

• User-Friendly: Use human-readable column and property names (no need for IDs)

• Auto-Authentication: Automatically handles login and session management

• Column Movement: Easily move cards between columns with simple property updates

Installation

Option 1: Using Claude CLI (Recommended)

The easiest way to install is using the Claude CLI with npx:

Replace the environment variable values with your actual Focalboard credentials:

• FOCALBOARD_HOST: Your Focalboard instance URL (e.g., https://focalboard.example.com)

• FOCALBOARD_USERNAME: Your Focalboard username or email

• FOCALBOARD_PASSWORD: Your Focalboard password

Alternatively, if you've cloned the repository locally:

Option 2: Manual Installation

1. Clone or download this repository

2. Install dependencies:

3. Build the project:

4. Add to your Claude Desktop configuration file:

MacOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

Replace /absolute/path/to/focalboard-mcp-server with the actual path to this project.

5. Restart Claude Desktop

Configuration

Required Environment Variables

• FOCALBOARD_HOST: The URL of your Focalboard instance (e.g., https://focalboard.example.com)

• FOCALBOARD_USERNAME: Your Focalboard username or email

• FOCALBOARD_PASSWORD: Your Focalboard password

Available Tools

Board Management

list_boards

List all boards for a team.

Parameters:

• teamId (optional): The team ID (default: "0")

Example:

get_board

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

Parameters:

• boardId (required): The board ID

Example:

search_boards

Search for boards by name or keyword.

Parameters:

• teamId (optional): The team ID (default: "0")

• searchTerm (required): Search term

Example:

Card/Task Operations

create_card

Create a new card (task) in a board with optional description.

Parameters:

• boardId (required): The board ID

• title (required): Card title

• properties (optional): Property values as key-value pairs using property names

• description (optional): Card description in markdown format

Example:

get_cards

List all cards in a board.

Parameters:

• boardId (required): The board ID

• page (optional): Page number (default: 0)

• perPage (optional): Results per page (default: 100)

Example:

get_card

Get detailed information about a specific card.

Parameters:

• cardId (required): The card ID

Example:

update_card

Update a card's properties, title, and/or description.

Parameters:

• cardId (required): The card ID

• boardId (required): The board ID

• title (optional): New title

• properties (optional): Property values to update using property names

• description (optional): Update or set the card description in markdown format

Example:

Moving Cards Between Columns: To move a card to a different column, update the property that defines the columns. For example, if your board has a "Status" property with columns "To Do", "In Progress", and "Done":

delete_card

Delete a card permanently.

Parameters:

• cardId (required): The card ID

• boardId (required): The board ID

Example:

add_card_description

Add or update the description of an existing card.

Parameters:

• cardId (required): The card ID

• boardId (required): The board ID

• description (required): The description content in markdown format

Example:

get_card_content

Get all content blocks (descriptions, text blocks, etc.) for a card.

Parameters:

• cardId (required): The card ID

Example:

Usage Examples

Getting Started

1. List your boards:

   List all my Focalboard boards

2. Get board details to see columns:

   Show me the details of board [board-id], including all columns

3. Create a new task:

   Create a task in board [board-id] titled "Review pull request" with Status "To Do"

4. Move a task to another column:

   Update card [card-id] in board [board-id], change Status to "Done"

Workflow Example

Working with Descriptions

Markdown Support: Descriptions support full markdown formatting:

• Bold and italic text

• Lists (ordered and unordered)

• Code blocks: `inline code` or ``` code block ```

• Headers (# H1, ## H2, etc.)

• Links: text

• And more!

How It Works

Authentication

The server automatically handles authentication:

1. When first called, it logs in with your username/password

2. Receives a session token from Focalboard

3. Uses the token for all subsequent API requests

4. Automatically re-authenticates if the token expires

Column Name Resolution

When you update a card with property names (e.g., "Status": "In Progress"):

1. The server fetches the board details

2. Finds the property by name (case-insensitive)

3. Resolves the column/option name to its internal ID

4. Updates the card with the correct ID

This means you can use friendly names like "To Do" instead of remembering cryptic IDs like "option-abc123".

API Reference

This server uses the Focalboard API v2. For more details, see:

• Focalboard API Documentation

• Focalboard GitHub Repository

Troubleshooting

Authentication Errors

If you see authentication errors:

• Verify your FOCALBOARD_HOST is correct (should include https://)

• Check your username and password are correct

• Ensure your Focalboard instance is accessible

Board or Card Not Found

• Use list_boards to get the correct board IDs

• Use get_cards to get valid card IDs

• Board and card IDs are case-sensitive

Property Not Found

• Use get_board to see all available properties and their names

• Property names are case-insensitive but must match exactly

• For select/multiSelect properties, option values must match available options

Development

Project Structure

Building

Watch Mode

For development with auto-rebuild:

License

MIT

Contributing

Contributions are welcome! Please feel free to submit issues or pull requests.

Related Projects

• Focalboard - Open source project management tool

• Model Context Protocol - Protocol for AI-application integration