kanban

mcp-kanban

A local-first Kanban board for AI agents, powered by the Model Context Protocol (MCP).

Table of Contents

• What is mcp-kanban?
• Quick Start (Claude Code)
• Other Agents
• Skills
• CLI Reference
• MCP Tools Reference
• How It Works
• Concepts
• Configuration
• Tech Stack
• Themes

What is mcp-kanban?

Most AI kanban tools try to be the orchestrator — spawning agents, managing worktrees, controlling execution. mcp-kanban doesn't. Your agent (Claude Code, Codex, Cursor) stays in control. mcp-kanban is just a board — agents report what they're doing through MCP tools, and you watch it happen in a real-time web UI. It fits into your existing workflow instead of replacing it.

Everything runs locally with SQLite, requires zero configuration, and launches with a single npx command.

Quick Start (Claude Code)

# In Claude Code, install the plugin
/plugin marketplace add gablabelle/claude-plugins
/plugin install kanban@gablabelle-plugins

Restart Claude Code, then try /kanban-plan to plan work. The board starts automatically.

What's included:

Component	What it does
MCP server	Connects Claude to the kanban board (create/move/update tickets)
/kanban-plan	Breaks work into stories and subtasks, opens the board so you can watch
/kanban-start	Starts the web UI server and opens the board
/kanban-work	Works through planned tickets, moving them through columns as it goes
/kanban-stop	Stops the web UI server
Stop hook	Reminds Claude to update ticket status when it forgets

Using Cursor, Codex, or another agent? See Other Agents below.

Other Agents

Claude Code (Manual)

If you prefer not to use the plugin system, you can set things up manually.

1. Connect the MCP server:

npx mcp-kanban provider add claude-code

2. Install skills and hook:

From your project root:

bash <(curl -s https://raw.githubusercontent.com/gablabelle/mcp-kanban/main/scripts/claude-install-remote.sh)

Or from a local clone:

bash /path/to/mcp-kanban/scripts/claude-install-plugin.sh

This copies skills to .claude/skills/ and adds the Stop hook to .claude/settings.json.

Cursor

1. Connect the MCP server:

npx mcp-kanban provider add cursor

This adds mcp-kanban to ~/.cursor/mcp.json.

2. Install skills (optional):

Cursor supports skills via .cursor/skills/ or .agents/skills/. Copy the skill files manually:

mkdir -p .cursor/skills/kanban-plan .cursor/skills/kanban-start .cursor/skills/kanban-work .cursor/skills/kanban-stop
curl -s https://raw.githubusercontent.com/gablabelle/mcp-kanban/main/plugin/skills/kanban-plan/SKILL.md -o .cursor/skills/kanban-plan/SKILL.md
curl -s https://raw.githubusercontent.com/gablabelle/mcp-kanban/main/plugin/skills/kanban-start/SKILL.md -o .cursor/skills/kanban-start/SKILL.md
curl -s https://raw.githubusercontent.com/gablabelle/mcp-kanban/main/plugin/skills/kanban-work/SKILL.md -o .cursor/skills/kanban-work/SKILL.md
curl -s https://raw.githubusercontent.com/gablabelle/mcp-kanban/main/plugin/skills/kanban-stop/SKILL.md -o .cursor/skills/kanban-stop/SKILL.md

3. Install hooks (optional):

Cursor supports hooks via .cursor/hooks.json. Create or merge the following:

{
  "version": 1,
  "hooks": {
    "stop": [
      {
        "command": "echo '{\"permission\": \"allow\", \"agent_message\": \"Check if you updated your mcp-kanban tickets. If you were working on kanban tickets, move completed ones to Done and update their descriptions.\"}'"
      }
    ]
  }
}

Codex

1. Connect the MCP server:

Add to ~/.codex/config.toml:

[mcp_servers.mcp-kanban]
command = "npx"
args = ["-y", "mcp-kanban", "mcp-server"]

Or use the CLI:

codex mcp add mcp-kanban -- npx -y mcp-kanban mcp-server

2. Install skills (optional):

Codex supports skills via .agents/skills/: