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

Related MCP server: kanban-mcp

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:

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

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

Note: Codex does not support hooks. The agent will still use the MCP tools, but won't get automatic reminders to update tickets.

Other MCP-Compatible Agents

For any agent that supports MCP, configure it to run mcp-kanban in stdio mode:

{
  "mcpServers": {
    "mcp-kanban": {
      "command": "npx",
      "args": ["-y", "mcp-kanban", "mcp-server"]
    }
  }
}

Skills

Skills teach your agent how to use the board effectively. They work with Claude Code, Cursor, and Codex.

/kanban-plan

Tell your agent what you want to build, and it breaks the work into stories and subtasks on the board. Starts the web UI and opens the browser so you can watch tickets appear in real-time. After planning, it asks if you want to start working.

/kanban-plan Add dark mode support with theme persistence

/kanban-start

Starts the web UI server and opens the board in the browser.

/kanban-start

/kanban-work

Works through planned tickets in priority order. For each subtask: moves it to In Progress, does the work, updates the ticket description with what was done, and marks it complete. Asks before moving to the next story.

/kanban-work

/kanban-stop

Stops the web UI server.

/kanban-stop

CLI Reference

Flags

MCP Tools Reference

Ticket Management

create_ticket

Create a new ticket on the Kanban board.

update_ticket

Update an existing ticket's fields.

move_ticket

Move a ticket to a different column.

delete_ticket

Delete a ticket.

Subtask Management

create_subtask

Create a subtask under a parent ticket.

complete_subtask

Mark a subtask as complete by moving it to Done.

Query Tools

list_tickets

List tickets with optional filters.

get_ticket

Get a ticket with its subtasks, attachments, and dependencies.

list_columns

List all columns for a project.

Board Management

open_board

Start the web UI server if not already running. Returns the board URL.

No parameters.

stop_board

Stop the web UI server.

No parameters.

Session Management

create_session

Create a new AI agent session.

delete_session

Delete an AI agent session. Tickets are preserved but unlinked.

list_sessions

List all AI agent sessions. No parameters.

How It Works

Repository ──> Project ──> Sessions (parallel agent runs)
                              |
                              └──> Tickets (assigned to sessions)
                                      |
                                      └──> Subtasks

1 Project = 1 Repository. Each project on the board corresponds to a codebase. A default project is created on first run.

Sessions = Agent Runs. Each session represents an individual AI agent execution. Sessions are automatically created from the git branch the agent is running in — if the agent runs on fix/login-bug, a session named "fix-login-bug" appears on the board. When using worktrees (e.g., claude --worktree feat/auth), the worktree's branch is detected the same way. All tickets the agent creates are tagged with its session and color-coded in the UI.

If the agent runs on the same branch again later, the existing session is reused — same color, same ticket history.

Typical agent workflow:

1. Agent starts — session auto-created from git branch

2. Creates tickets for its plan (auto-tagged with session)

3. Moves tickets through columns as it works (Backlog → Todo → In Progress → Review → Done)

4. Breaks stories into subtasks, completes them as it goes

5. Parent tickets show progress bars based on subtask completion

Multiple agents can work in parallel on different branches or worktrees, each with their own session. The board shows all sessions at once, color-coded so you can visually track which agent is doing what.

Concepts

• Projects — Separate boards, typically one per repository. A default project is created on first run.

• Columns — Workflow stages: Backlog → Todo → In Progress → Review → Done.

• Tickets — Tasks with title, description (Markdown), priority, and session assignment.

• Subtasks — Full tickets nested under a parent. Parent tickets show a progress bar based on subtask completion.

• Sessions — AI execution contexts, auto-created from the git branch. One session per branch or worktree. Reused across agent runs on the same branch. Tickets are color-coded by session. Sessions with branch metadata show a git branch icon in the UI. You can also create sessions manually via the UI or create_session tool.

• Priority — urgent, high, medium, low.

Configuration

Tech Stack

TypeScript, Hono, React, Vite, Tailwind CSS, dnd-kit, Drizzle ORM, better-sqlite3, MCP SDK

Themes

A few themes are provided, each with light and dark mode. They need refinement. This is work in progress. ;-)

Default

Glass

Brutalist

Softnight

License

MIT