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:

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

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:

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

1. Clone or download this repository

2. Install dependencies:

npm install

3. Build the project:

npm run build

4. Add to your Claude Desktop configuration file:

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

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

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:

List all my boards

get_board

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

Parameters:

• boardId (required): The board ID

Example:

Get details for board abc123

search_boards

Search for boards by name or keyword.

Parameters:

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

• searchTerm (required): Search term

Example:

Search for boards with "project" in the name

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:

Create a card titled "Implement login feature" in board abc123 with Status "To Do" and Priority "High" and description "Add OAuth2 authentication with Google and GitHub providers"

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 all cards from board abc123

get_card

Get detailed information about a specific card.

Parameters:

• cardId (required): The card ID

Example:

Get details for card xyz789

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:

Update card xyz789 in board abc123, move it to "In Progress" status and add description "Currently implementing the authentication flow"

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":

Update card xyz789, set Status to "In Progress"

delete_card

Delete a card permanently.

Parameters:

• cardId (required): The card ID

• boardId (required): The board ID

Example:

Delete card xyz789 from board abc123

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:

Add description to card xyz789: "This task involves implementing user authentication with JWT tokens"

get_card_content

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

Parameters:

• cardId (required): The card ID

Example:

Get the description and content of card xyz789

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

User: "List all my boards"
Claude: [Shows list of boards with IDs]

User: "Get details for board abc123"
Claude: [Shows board with property definitions, including Status column options]

User: "Create a card in board abc123 titled 'Fix bug in authentication' with Status 'To Do' and Priority 'High'"
Claude: [Creates card and returns the new card ID]

User: "Get all cards from board abc123"
Claude: [Shows all cards in the board]

User: "Update card xyz789, move it to 'In Progress'"
Claude: [Updates the card's Status property]

Working with Descriptions

User: "Create a task in board abc123 titled 'Implement OAuth' with description 'Add Google and GitHub OAuth providers'"
Claude: [Creates card with description]

User: "Show me the description of card xyz789"
Claude: [Retrieves and displays the card's content blocks including the description]

User: "Update card xyz789 description to include implementation details"
Claude: [Updates the card's description]

User: "Add a description to card abc456 explaining the requirements"
Claude: [Adds a new description to an existing card]

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

focalboard-mcp-server/
├── src/
│   ├── index.ts              # MCP server entry point
│   ├── focalboard-client.ts  # Focalboard API client
│   └── types.ts              # TypeScript type definitions
├── package.json
├── tsconfig.json
└── README.md

Building

npm run build

Watch Mode

For development with auto-rebuild:

npm run watch

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