kanbantool-mcp

An MCP server that connects Claude Code (and other MCP clients) to a Kanban Tool account.

New to MCP? This is an MCP server — you run it from an MCP-aware assistant. If you've never set one up, install Claude Code, Claude Desktop, or Cursor first, then come back here.

Why this exists

Kanban Tool holds the authoritative state of your boards, tasks, and workflow — but an LLM can't see any of it without help. This MCP server gives Claude Code (and any other MCP client) read access to boards and tasks, search via Kanban Tool's query DSL, and write tools to create, update, move, archive, comment on, and break down tasks. The point: stop re-explaining your kanban state to the model on every interaction, and let it act on the board directly when you want it to.

Status

Alpha, approaching v1.0. The 26-tool surface is settled and exercised against a real Kanban Tool account via the Live Integration workflow. Pre-1.0 means the surface may still evolve based on real-world feedback — pin a specific version if you need stability across upgrades. See SEMVER.md for the v1.0 stability commitment (which surfaces are stable, which are not, deprecation policy).

Roadmap & support

Where the project is going: see the open milestones. Larger workstreams are tagged with the epic label.

Maintainer is best-effort and typically responds to issues and PRs within ~a week. If something is blocking you and the silence is longer, a polite bump on the thread is welcome.

What this looks like

A short illustrative session — the shape of an interaction, not literal terminal output:

User:      What's on my Engineering board right now?
Assistant: (calls list_boards)            -> finds "Engineering" with id 4217
           (calls get_board 4217)         -> reads columns: Backlog / Doing / Review / Done
           (calls search_tasks
              query="archived:false",
              board_id=4217)              -> 14 active tasks, grouped by column

           Engineering has 14 active cards. Doing (3): "Migrate auth to OIDC",
           "Flaky CI on macOS", "Add rate-limit headers". Review (2): ...

Longer end-to-end walkthroughs (with realistic JSON request/response shapes) live in examples/.

Install

Configuration

The first two are required; the rest are optional and unset by default.

Wiring it into your client

The JSON shape is the same across MCP clients — only the file location and the launcher CLI differ. Pick your client below, drop the snippet into the matching mcp.json, and substitute your KANBANTOOL_DOMAIN / KANBANTOOL_API_TOKEN values.

Each snippet shows the PyPI form (uvx kanbantool-mcp) — swap the args for the git form below if you want to track main instead of a release:

"args": ["--from", "git+https://github.com/VeryLongOrgNameSuchWow/kanbantool-mcp", "kanbantool-mcp"]

Claude Code

Easiest path is the CLI:

claude mcp add-json kanbantool '{
  "command": "uvx",
  "args": ["kanbantool-mcp"],
  "env": {
    "KANBANTOOL_DOMAIN": "your-account",
    "KANBANTOOL_API_TOKEN": "your-token"
  }
}'

Or edit ~/.claude.json (project-scoped via claude mcp add-json -s project ...). See https://docs.claude.com/en/docs/claude-code/mcp for scopes.

Claude Desktop

Edit the config file (~/Library/Application Support/Claude/claude_desktop_config.json on macOS, %APPDATA%\Claude\claude_desktop_config.json on Windows). Setup docs: https://modelcontextprotocol.io/quickstart/user.

{
  "mcpServers": {
    "kanbantool": {
      "command": "uvx",
      "args": ["kanbantool-mcp"],
      "env": {
        "KANBANTOOL_DOMAIN": "your-account",
        "KANBANTOOL_API_TOKEN": "your-token"
      }
    }
  }
}

Cursor

Edit ~/.cursor/mcp.json (or per-project .cursor/mcp.json). Setup docs: https://cursor.com/docs/mcp.

{
  "mcpServers": {
    "kanbantool": {
      "command": "uvx",
      "args": ["kanbantool-mcp"],
      "env": {
        "KANBANTOOL_DOMAIN": "your-account",
        "KANBANTOOL_API_TOKEN": "your-token"
      }
    }
  }
}

Continue

Edit ~/.continue/config.yaml (Continue uses YAML, not JSON, for MCP entries). Setup docs: https://docs.continue.dev/customize/deep-dives/mcp.

mcpServers:
  - name: kanbantool
    command: uvx
    args:
      - kanbantool-mcp
    env:
      KANBANTOOL_DOMAIN: your-account
      KANBANTOOL_API_TOKEN: your-token

Cline

Edit cline_mcp_settings.json via the Cline panel's MCP Servers > Edit Config button. Setup docs: https://docs.cline.bot/mcp/configuring-mcp-servers.

{
  "mcpServers": {
    "kanbantool": {
      "command": "uvx",
      "args": ["kanbantool-mcp"],
      "env": {
        "KANBANTOOL_DOMAIN": "your-account",
        "KANBANTOOL_API_TOKEN": "your-token"
      }
    }
  }
}

Generic MCP-over-stdio

Any MCP client that supports launching a stdio server. Spawn this command with the env vars set in the child process; the server speaks JSON-RPC on stdin/stdout.

KANBANTOOL_DOMAIN=your-account \
  KANBANTOOL_API_TOKEN=your-token \
  uvx kanbantool-mcp

Read-only mode

Set KANBANTOOL_READ_ONLY=1 (or true/yes/on) to register only the 11 read-class tools. Any value outside that set, including the empty string, leaves the full 26-tool surface intact.

Use this when you want to give an LLM safe access to your boards — search, browse, summarise, answer questions about state — without giving it the ability to create, update, move, archive, comment on, or delete anything. The write tools simply don't appear in the tool list, so the model can't call them even if it tried.

Read-class tools (always registered):

list_boards            get_board                       get_user
search_tasks           list_board_collaborators        whoami
get_task               list_custom_field_definitions   list_my_timers
recent_changes         list_subtasks

Write tools (suppressed when read-only): create_task, update_task, move_task, archive_task, set_custom_field, add_comment, delete_comment, add_subtask, update_subtask, delete_subtask, reorder_subtasks, start_timer, stop_timer, delete_timer.

The transport smoke test ping is always registered regardless of mode.

Verify your install

Run kanbantool-mcp --check (e.g. uvx kanbantool-mcp --check) — it validates your env vars, hits the whoami endpoint, and prints a one-line OK/FAIL signal. Sample success output:

OK: Alice Example (your-account) — token resolves; you can use kanbantool-mcp now

The flag exits 0 on success and non-zero on failure (missing env, 401/403 auth, network failure), with an actionable hint per error class. Run it once after wiring the server into your client to confirm the token reaches Kanban Tool before asking your assistant to do anything with it.

To check which version you have installed, run kanbantool-mcp --version (e.g. uvx kanbantool-mcp --version). Useful when reporting an issue.

You can also verify from inside the assistant: ask "who am I?" — it'll call the whoami tool and confirm your token resolves. If that comes back with your name, the server is reachable and your credentials work.

Tool reference

(ping exists as a transport smoke test; not listed above.)

What this server does not cover

The tool surface is bounded by what the Kanban Tool API v3 actually exposes. A few common workflows are intentionally absent because there is no upstream endpoint to call:

• Board lifecycle. The API has no POST /boards, PUT /boards/{id}, or DELETE /boards/{id} — boards must be created, renamed, and archived through the Kanban Tool web UI, not via the MCP. list_boards and get_board are the only board-scoped surfaces. Verified via live spike against the API (every variant returns 404; see #130). Provision the board out-of-band first, then point the LLM at it.

• Column / swimlane structure. Board.columns and Board.swimlanes are read-only on the wire. Re-shape your workflow in the web UI; the MCP can read the result but not edit it.

• Comment editing. The API has no comment-edit endpoint. delete_comment + add_comment is the supported "fix a comment" pattern.

• Webhooks. Kanban Tool ships none. recent_changes(board_id, since) is the polling primitive that stands in.

• Bulk user listing. No global /users endpoint. list_board_collaborators(board_id) is the canonical user-discovery surface (per board).

Per the project's "be honest about the upstream" principle (see CLAUDE.md), these gaps are surfaced explicitly rather than papered over with shims.

Examples

A short write-flow alongside the read-flow shown above. Illustrative — shape of a session, not literal terminal output. For longer walkthroughs with realistic JSON shapes, see examples/.

User:      Create a high-priority task in Engineering called "Fix login bug",
           and leave a comment that I'm picking it up today.
Assistant: (calls list_boards)             -> resolves "Engineering" -> id 4217
           (calls create_task
              name="Fix login bug",
              board_id=4217,
              priority="high")             -> task id 88231 created
           (calls add_comment
              task_id=88231,
              content="Picking this up today.")

           Created "Fix login bug" (id 88231) in Engineering at high priority,
           and added your comment.

Development

git clone https://github.com/VeryLongOrgNameSuchWow/kanbantool-mcp.git
cd kanbantool-mcp
uv sync
uv run pytest
uv run ruff check .
uv run ty check

Tests are offline-only and mock HTTP via respx — no Kanban Tool account needed to contribute.

Documentation

License

MIT