Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/fulsomenko/kanban/llms.txt

Use this file to discover all available pages before exploring further.

​
Overview

The kanban MCP server provides full read/write access to your boards, cards, columns, and sprints over the Model Context Protocol. This enables LLM tools like Claude Code, Cursor, and other MCP-compatible applications to interact with your kanban boards programmatically.

​
Architecture

The MCP server uses a subprocess delegation architecture, executing all operations through the kanban CLI: 
┌─────────────────┐
│  Claude/MCP     │
│    Client       │
└────────┬────────┘
         │ JSON-RPC
         ▼
┌─────────────────────────────────────────────┐
│              kanban-mcp                      │
│  ┌─────────────────────────────────────┐    │
│  │  MCP Tool Handlers                   │    │
│  │  - create_board → spawn CLI          │    │
│  │  - list_cards → spawn CLI            │    │
│  │  - move_card → spawn CLI             │    │
│  └─────────────────────────────────────┘    │
│  ┌─────────────────────────────────────┐    │
│  │  CliExecutor                         │    │
│  │  - spawn("kanban", args)             │    │
│  │  - parse CliResponse<T>              │    │
│  │  - retry on conflict                 │    │
│  └─────────────────────────────────────┘    │
└────────┬────────────────────────────────────┘
         │ subprocess
         ▼
┌─────────────────┐
│  kanban CLI     │
│  (executable)   │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│  kanban.json    │  ← Atomic writes + conflict detection
└─────────────────┘
This architecture provides several benefits:
  • Single source of truth: CLI is the canonical implementation
  • Automatic capability inheritance: New CLI commands automatically become available
  • Decoupled runtime: Only binary dependency, no shared Rust library code
  • Natural conflict handling: Each subprocess reloads state from disk

​
Installation

The Nix derivation automatically wraps the binary with the kanban CLI in PATH: 
nix build .#kanban-mcp

​
From Cargo

cargo install --path crates/kanban-mcp

# Ensure kanban CLI is in PATH
cargo install --path crates/kanban-cli

​
Launch

nix run github:fulsomenko/kanban#kanban-mcp
Or with a specific data file: 
kanban-mcp /path/to/kanban.json

​
Configuration

Add the MCP server to your LLM tool’s configuration.

​
Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json: 
{
  "mcpServers": {
    "kanban": {
      "command": "nix",
      "args": ["run", ".#kanban-mcp", "--", "kanban.json"]
    }
  }
}

​
Example from Repository

See .mcp.json in the repository root:
.mcp.json
{
  "mcpServers": {
    "kanban": {
      "command": "nix",
      "args": ["run", ".#kanban-mcp", "--", "kanban.json"]
    }
  }
}

​
Available Operations

The MCP server exposes the following tools:

Board Operations

  • create_board - Create a new kanban board
  • list_boards - List all boards
  • get_board - Get a specific board by ID
  • delete_board - Delete a board and all its contents

Column Operations

  • create_column - Create a new column in a board
  • list_columns - List columns in a board
  • delete_column - Delete a column and its cards

Card Operations

  • create_card - Create a new card in a column
  • list_cards - List cards with optional filters
  • get_card - Get a specific card by ID
  • move_card - Move a card to a different column
  • update_card - Update card properties
  • archive_card - Archive a card
  • delete_card - Permanently delete a card

Sprint Operations

  • create_sprint - Create a new sprint
  • list_sprints - List all sprints
  • activate_sprint - Activate a sprint
  • complete_sprint - Mark a sprint as complete
  • assign_card_to_sprint - Assign cards to sprints

​
CLI Command Mapping

Each MCP tool maps directly to a CLI command:
MCP ToolCLI Command
create_boardkanban board create --name X
list_boardskanban board list
get_boardkanban board get <id>
delete_boardkanban board delete <id>
create_columnkanban column create --board-id X --name Y
list_columnskanban column list --board-id X
delete_columnkanban column delete <id>
create_cardkanban card create --board-id X --column-id Y --title Z
list_cardskanban card list --board-id X
get_cardkanban card get <id>
move_cardkanban card move <id> --column-id X
update_cardkanban card update <id> --title X
archive_cardkanban card archive <id>
delete_cardkanban card delete <id>

​
Concurrency & Conflict Resolution

The MCP server includes automatic retry logic with exponential backoff when file conflicts occur: 
Attempt 1 → ConflictDetected → Wait 50ms
Attempt 2 → ConflictDetected → Wait 100ms
Attempt 3 → Success ✓
Default Configuration:
  • Max attempts: 3
  • Initial delay: 50ms
  • Max delay: 1000ms
  • Backoff multiplier: 2.0x
This retry mechanism works seamlessly with the kanban CLI’s optimistic concurrency control:
  1. Load: Read file + capture metadata (mtime, size, hash)
  2. Modify: Execute operation in memory
  3. Save: Verify metadata unchanged, then atomic write
  4. Conflict: If metadata changed, return error (MCP server retries)
See Multi-Instance Support for more details on conflict detection.

​
CLI Response Format

The kanban CLI returns structured JSON responses that the MCP server parses: Success: 
{
  "success": true,
  "api_version": "0.1.0",
  "data": { ... }
}
Error: 
{
  "success": false,
  "api_version": "0.1.0",
  "error": "Error message"
}

​
Source Code

The MCP server implementation is located in crates/kanban-mcp/:
  • src/main.rs - MCP server entry point
  • src/tools.rs - Tool definitions and handlers
  • src/executor.rs - CLI subprocess execution with retry logic

View on GitHub

Explore the full MCP server source code

Build docs developers (and LLMs) love

Get started for freeTalk to us