kanban-mcp
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@kanban-mcp Show all open issues in the current project"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
kanban-mcp
A database-backed kanban board that AI coding agents use via MCP (Model Context Protocol). Track issues, features, todos, epics, and diary entries across all your projects — with a web UI for humans and 40+ tools for agents.


What It Does
Persistent project tracking — issues, features, todos, epics, questions, diary entries stored in SQLite (default) or MySQL/MariaDB
Status workflows — each item type has its own progression (backlog → todo → in_progress → review → done → closed)
Relationships & epics — parent/child hierarchies, blocking relationships, epic progress tracking
Tags, decisions, file links — attach metadata to any item
Semantic search — find similar items using local ONNX embeddings (optional; downloads nomic-embed-text-v1.5 from HuggingFace on first use, ~140MB — the first query will block until download completes)
Activity timeline — unified view of status changes, decisions, updates, and git commits
Export — JSON, YAML, or Markdown output with filters
Web UI — browser-based board at localhost:5000
Session hooks — inject active items into AI agent sessions automatically
Related MCP server: TaskForge
Quick Start
Requires Python 3.10+.
Linux / macOS:
curl -fsSL https://raw.githubusercontent.com/multidimensionalcats/kanban-mcp/main/install.sh | bashWindows (PowerShell):
irm https://raw.githubusercontent.com/multidimensionalcats/kanban-mcp/main/install.ps1 | iexThe script prompts interactively (backend choice, etc.) then installs pipx and kanban-mcp, sets up the database, runs migrations, and prints your MCP config. SQLite is the default — just press Enter. No database server required.
Want MySQL/MariaDB instead? Add --mysql (or -MySQL on Windows):
curl -fsSL https://raw.githubusercontent.com/multidimensionalcats/kanban-mcp/main/install.sh | bash -s -- --auto --mysqlManual install (no script):
pipx install kanban-mcp
kanban-cli --project "$(pwd)" summary # SQLite DB auto-created on first runThen add the MCP server to your AI client — see MCP Client Setup.
Prerequisites
Python 3.10+
pipx (recommended) — installed automatically by the install script if missing
MySQL 8.0+ or MariaDB 11+ (optional) — only needed if you choose MySQL over the default SQLite backend
Installation
The Quick Start one-liner is the fastest path. Below are alternative install methods and additional options.
Option 1: pipx (recommended)
pipx installs into an isolated virtualenv while making commands globally available. This avoids PEP 668 conflicts on modern distros and ensures hooks work outside the venv.
# SQLite backend (default, zero dependencies)
pipx install kanban-mcp
# With semantic search
pipx install kanban-mcp[semantic]
# With MySQL backend
pipx install kanban-mcp[mysql]
# Everything (MySQL + semantic)
pipx install kanban-mcp[full]The SQLite database is created automatically on first run — no extra setup needed. For MySQL, see Database Setup.
Upgrade later with:
pipx upgrade kanban-mcpOption 2: pip
pip install --user kanban-mcpNote: On modern distros (Debian 12+, Fedora 38+, Arch, Gentoo), bare
pip installis blocked by PEP 668. Use--user,--break-system-packages, or prefer pipx.
Option 3: From source (development)
git clone https://github.com/multidimensionalcats/kanban-mcp.git
cd kanban-mcp
pip install -e .[dev]Note: If PEP 668 blocks the install, use a venv:
python3 -m venv .venv && source .venv/bin/activatefirst. Be aware that hooks run via/bin/sh, not the venv Python — you'll need to use full paths to the venv's console scripts in your hook configuration.
Option 4: Docker (MySQL/MariaDB + web UI)
Note: Docker compose runs MySQL/MariaDB, not SQLite. Use this if you want a containerized MySQL setup.
The install script can start MySQL/MariaDB via Docker for you (./install.sh --auto --mysql --docker or choose Docker when prompted). To run the compose stack manually:
Start the containers (MySQL 8.0 + web UI on port 5000):
git clone https://github.com/multidimensionalcats/kanban-mcp.git cd kanban-mcp docker compose upMigrations run automatically on web container startup. Credentials are configurable:
KANBAN_DB_USER=myuser KANBAN_DB_PASSWORD=secret docker compose upInstall the MCP server on the host — Docker only provides the database and web UI. MCP clients spawn the server as a subprocess, so it must be installed locally:
pipx install kanban-mcp[mysql]Configure your MCP client — see MCP Client Setup. The database is exposed on port 3306 so the host-side MCP server can connect.
Database Setup
kanban-mcp uses SQLite by default — no setup required. The database
file is created automatically on first run at ~/.local/share/kanban-mcp/kanban.db
(or $XDG_DATA_HOME/kanban-mcp/kanban.db). You do not need to run kanban-setup
for SQLite — it is only necessary if you want a custom database path or MySQL.
kanban-setup --auto defaults to SQLite. To choose a custom path:
kanban-setup --auto --backend sqlite --sqlite-path /path/to/dbNote:
kanban-setup --with-semanticinstalls the semantic search Python packages. This is only needed if you installed without[semantic]initially (e.g.pipx install kanban-mcp). If you already installed withkanban-mcp[semantic], you don't need this flag. Works with any backend.
MySQL/MariaDB (optional)
If you need MySQL/MariaDB instead of SQLite:
Automated (interactive)
kanban-setupPrompts for database name, user, password, and MySQL/MariaDB root credentials (including root password), then creates the database, runs migrations, and writes credentials to ~/.config/kanban-mcp/.env.
Note: On Debian/Ubuntu,
default-mysql-serverinstalls MariaDB, which defaults toauth_socketfor the root user. Socket auth only works when the OS user matches the MySQL user (i.e. running as OS root). For non-root users, provide the MySQL root password when prompted — this is the normal path.
Automated (non-interactive / AI agents)
The --auto flag skips all interactive prompts. Without it, kanban-setup will prompt for each value.
# With root password (most common)
kanban-setup --auto --backend mysql --mysql-root-password rootpass
# With explicit credentials via environment variables
KANBAN_DB_NAME=kanban KANBAN_DB_USER=kanban KANBAN_DB_PASSWORD=secret \
MYSQL_ROOT_PASSWORD=rootpass kanban-setup --auto --backend mysql
# With CLI args
kanban-setup --auto --backend mysql --db-name mydb --db-user myuser --db-password secret
# Socket auth (only works when OS user matches MySQL user, e.g. running as root)
kanban-setup --auto --backend mysqlImportant:
MYSQL_ROOT_PASSWORDis required for non-interactive use unless you are running as OS root. Socket auth (auth_socket) only works when the OS user matches the MySQL user — this is uncommon outside of CI or Docker. On Debian/Ubuntu, MariaDB defaults root toauth_socket— setMYSQL_ROOT_PASSWORDor use the manual SQL setup below.
Install script reference
The install scripts can be run from the repo or downloaded standalone:
./install.sh # interactive (asks backend, installs pipx/kanban-mcp)
./install.sh --auto # non-interactive, SQLite (default, zero config)
./install.sh --auto --mysql # non-interactive, local MySQL/MariaDB (socket auth)
MYSQL_ROOT_PASSWORD=rootpass ./install.sh --auto --mysql # non-interactive, MySQL with root password
./install.sh --auto --mysql --docker # non-interactive, MySQL via Docker
./install.sh --auto --mysql --db-host HOST # non-interactive, remote MySQL
./install.sh --upgrade # upgrade existing Docker install
.\install.ps1 # Windows interactive
.\install.ps1 -Auto # Windows non-interactive (SQLite)
.\install.ps1 -Auto -MySQL # Windows MySQL
.\install.ps1 -Auto -MySQL -Docker # Windows MySQL via Docker
.\install.ps1 -Auto -MySQL -DbHost HOST # Windows remote MySQL
.\install.ps1 -Upgrade # upgrade existing Docker installEnv Variable | Default | Description |
|
| Backend: |
|
| SQLite database file path |
|
| MySQL database name |
|
| Database user |
| (auto-generated) | Database password |
|
| Database host |
|
| Database port |
|
| Database admin user |
| (none — tries socket auth) | Database admin password (required unless running as OS root) |
Manual
Manual setup is a good alternative if database root auth is problematic (e.g. socket auth issues, restricted access).
-- As MySQL/MariaDB root user:
CREATE DATABASE kanban CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
CREATE USER 'kanban'@'localhost' IDENTIFIED BY 'your_password_here';
CREATE USER 'kanban'@'%' IDENTIFIED BY 'your_password_here';
GRANT ALL PRIVILEGES ON `kanban`.* TO 'kanban'@'localhost';
GRANT ALL PRIVILEGES ON `kanban`.* TO 'kanban'@'%';
FLUSH PRIVILEGES;Note: On MariaDB,
'kanban'@'%'does not match localhost socket connections — you need both the@'localhost'and@'%'users.
Run the migration files in order:
mysql -u kanban -p kanban < kanban_mcp/migrations/001_initial_schema.sql
mysql -u kanban -p kanban < kanban_mcp/migrations/002_add_fulltext_search.sql
mysql -u kanban -p kanban < kanban_mcp/migrations/003_add_embeddings.sql
mysql -u kanban -p kanban < kanban_mcp/migrations/004_add_cascades_and_indexes.sqlConfiguration
Credentials
kanban-setup writes database credentials to a .env file in the user config directory:
Linux/macOS:
~/.config/kanban-mcp/.env(or$XDG_CONFIG_HOME/kanban-mcp/.env)Windows:
%APPDATA%\kanban-mcp\.env
All install methods (pipx, pip, source) use this same location. You can also set credentials via environment variables or your MCP client's env block.
Precedence (highest to lowest): MCP client env block → shell environment variables → .env file. In practice, just use one method — the .env file from kanban-setup is simplest.
Warning: If you previously used MySQL and switch to SQLite, remove or rename the old
.envfile at~/.config/kanban-mcp/.env. LeftoverKANBAN_DB_USER/KANBAN_DB_PASSWORD/KANBAN_DB_NAMEvalues will silently trigger MySQL auto-detection. Alternatively, setKANBAN_BACKEND=sqliteexplicitly to override.
Variable | Required | Default | Description |
| No | (auto-detect) | Force backend: |
| No |
| SQLite database file path |
| No |
| MySQL database server host |
| No |
| MySQL database server port |
| Yes (MySQL only) | — | MySQL database username |
| Yes (MySQL only) | — | MySQL database password |
| Yes (MySQL only) | — | MySQL database name |
| No |
| MySQL connection pool size |
| No | — | Override project directory detection |
| No |
| Web UI port ( |
| No |
| Web UI bind address ( |
MCP Client Setup
The kanban-mcp server speaks JSON-RPC 2.0 over stdin/stdout (standard MCP STDIO transport). Any MCP client can use it. If kanban-setup already wrote your .env file, you only need the command — no env block required.
If you need to pass credentials explicitly (e.g. the client doesn't inherit your shell environment), add an env block:
"env": {
"KANBAN_DB_HOST": "localhost",
"KANBAN_DB_USER": "kanban",
"KANBAN_DB_PASSWORD": "your_password_here",
"KANBAN_DB_NAME": "kanban"
}Claude Code
Add to ~/.claude.json (global) or .mcp.json (per-project):
{
"mcpServers": {
"kanban": {
"command": "kanban-mcp"
}
}
}Claude Desktop
Add to ~/.config/Claude/claude_desktop_config.json (Linux) or ~/Library/Application Support/Claude/claude_desktop_config.json (macOS):
{
"mcpServers": {
"kanban": {
"command": "kanban-mcp"
}
}
}Gemini CLI
Add to ~/.gemini/settings.json:
{
"mcpServers": {
"kanban": {
"command": "kanban-mcp"
}
}
}VS Code / Copilot
Add to .vscode/mcp.json (per-project):
{
"servers": {
"kanban": {
"command": "kanban-mcp"
}
}
}Note: VS Code uses the key
servers, notmcpServers.
Codex CLI
Add to ~/.codex/config.toml:
[mcp_servers.kanban]
command = "kanban-mcp"Cursor
Add to .cursor/mcp.json (per-project):
{
"mcpServers": {
"kanban": {
"command": "kanban-mcp"
}
}
}Other MCP Clients
For any other MCP-compatible tool: point it at the kanban-mcp command with STDIO transport. With the default SQLite backend, no env configuration is needed. If using MySQL and the tool can't read the .env file (e.g. it doesn't inherit your shell environment), pass the KANBAN_DB_* variables via the client's env configuration.
Hooks
Hooks are what make the agent use the board automatically. Without them, the agent only interacts with kanban-mcp when you explicitly ask it to.
Two hooks ship as console scripts, installed alongside kanban-mcp:
kanban-hook-session-start — Runs at session start. Reads the project directory from the hook's stdin JSON (cwd field), looks up the project in the database, and prints any in-progress items. This output gets injected into the conversation context, so the agent knows what's active without being told.
kanban-hook-stop — Runs at session end. Lists items still in progress and suggests creating a diary entry, updating statuses, or adding progress notes. This nudges the agent (and you) to keep the board current.
Both hooks exit silently if the project isn't tracked or the database is unreachable — they never block a session.
Which clients support hooks?
Client | Session hooks? | Config location |
Claude Code | Yes |
|
Gemini CLI | Yes |
|
VS Code Copilot | Yes (preview) |
|
Copilot CLI | Yes | Hook config files |
Cursor | Yes (plugin primitive) | Hook config |
¹ VS Code Copilot reads Claude Code's hook configuration — if you already configured hooks for Claude Code, VS Code Copilot will use them too.
Claude Code, Gemini CLI, and VS Code Copilot all use the same hook format. Gemini CLI also sets CLAUDE_PROJECT_DIR as a compatibility alias, so the kanban hooks work across all three without modification.
Configuration
Hooks run via /bin/sh (Linux/macOS) or cmd (Windows), which do not read shell profiles — you must use absolute paths.
Find your paths:
# Linux/macOS
which kanban-hook-session-start # typically ~/.local/bin/kanban-hook-session-start
which kanban-hook-stop# Windows
Get-Command kanban-hook-session-start | Select-Object -ExpandProperty Source
# typically C:\Users\<you>\pipx\venvs\kanban-mcp\Scripts\kanban-hook-session-start.exeMerge into your client's settings file (~/.claude/settings.json for Claude Code and VS Code Copilot, ~/.gemini/settings.json for Gemini CLI):
Linux/macOS:
{
"hooks": {
"SessionStart": [
{ "hooks": [{ "type": "command", "command": "/home/you/.local/bin/kanban-hook-session-start" }] }
],
"Stop": [
{ "hooks": [{ "type": "command", "command": "/home/you/.local/bin/kanban-hook-stop" }] }
]
}
}Windows:
{
"hooks": {
"SessionStart": [
{ "hooks": [{ "type": "command", "command": "C:\\Users\\you\\pipx\\venvs\\kanban-mcp\\Scripts\\kanban-hook-session-start.exe" }] }
],
"Stop": [
{ "hooks": [{ "type": "command", "command": "C:\\Users\\you\\pipx\\venvs\\kanban-mcp\\Scripts\\kanban-hook-stop.exe" }] }
]
}
}If you already have hooks configured, add the kanban entries to your existing arrays — don't replace them.
Tip:
install.shandinstall.ps1print a ready-to-use config snippet with your resolved paths after setup completes.
Usage
First session
Once installed and configured, open your AI agent in a project directory. The first time you do this:
The session start hook fires but exits silently (it doesn't know about this project yet)
The agent needs to call
set_current_projectwith your working directory's absolute path — this auto-creates the project in the databaseFrom this point, all kanban tools work against this project
At session end, the stop hook lists any in-progress items and suggests logging progress
On subsequent sessions in the same directory, the start hook injects your active items into the conversation automatically — the agent picks up where you left off.
There is no "create project" command. Projects are created implicitly the first time set_current_project is called for a directory. If the agent doesn't call it on its own, ask it to — or the hooks will handle project context once the project exists in the database.
Note: Paths are resolved (symlinks,
.,..) before hashing, so--project .and--project $PWDrefer to the same project. The same applies toset_current_project.
Three interfaces
kanban-mcp provides three ways to interact with the same data:
MCP tools — 40+ tools the AI agent calls during conversation. This is the primary interface. The agent creates items, tracks dependencies, advances statuses, and logs progress as part of your normal workflow. You don't need to tell it to — the session hooks provide context and the agent uses the tools naturally.
Web UI — a browser-based kanban board for humans.
kanban-web # http://127.0.0.1:5000
kanban-web --port 8080 # custom port
kanban-web --host 0.0.0.0 # network-accessible (no auth — use with care)
KANBAN_WEB_PORT=8080 kanban-web # port via env varkanban-web runs in the foreground. To run it persistently, use a process manager (e.g. systemd, screen, tmux) or the Docker compose stack which includes the web UI.
macOS note: Port 5000 is used by AirPlay Receiver on modern macOS. If
kanban-webfails to bind, use--port 5001or setKANBAN_WEB_PORT=5001.
The board shows all status columns (backlog → todo → in_progress → review → done → closed) with drag-and-drop between them. Use the project dropdown in the header to switch between projects. Cards show priority, tags, epic membership, blocking relationships, and progress bars for epics.
CLI — kanban-cli for terminal queries, scripts, and exports. Every command takes --project PATH (the same directory path you'd use with your agent) and an optional --format {text,json}.
CLI reference
All commands take --project PATH with the absolute path to your project directory, and an optional --format {text,json}.
# What's currently being worked on?
kanban-cli --project /path/to/project active
# What's in the backlog?
kanban-cli --project /path/to/project todos
# Project overview — counts by type and status
kanban-cli --project /path/to/project summary
# Search items and updates
kanban-cli --project /path/to/project search "authentication"
# Semantic search (requires [semantic] extra)
kanban-cli --project /path/to/project semantic-search "auth problems" --limit 5
# Export the full board
kanban-cli --project /path/to/project export --format markdown
kanban-cli --project /path/to/project export --format json --metrics --relationships
# Get children of an epic
kanban-cli --project /path/to/project children 42 --recursive
# Context dump (what the session hooks use internally)
kanban-cli --project /path/to/project context
# Rebuild embeddings after bulk changes
kanban-cli --project /path/to/project rebuild-embeddingsTip: Paths are resolved (symlinks,
.,..) before hashing, so--project .and--project $PWDrefer to the same project.
Upgrading
Database migrations run automatically on startup — no manual migration step needed after upgrading.
pipx:
pipx upgrade kanban-mcppip:
pip install --user --upgrade kanban-mcpFrom source:
cd kanban-mcp && git pull && pip install -e .[dev]Docker:
./install.sh --upgrade
# Windows: .\install.ps1 -UpgradeThis re-downloads the latest Docker files, rebuilds the web image from PyPI, and restarts the containers. Migrations run automatically on container startup.
For AI Coding Agents
Claude, Gemini, GPT, Codex, and other agents: start here.
If your human has asked you to install kanban-mcp, follow these steps exactly. Do not improvise. The --auto flag handles all prompts.
1. Install and set up the database
The default path uses SQLite — zero config, no database server needed:
curl -fsSL https://raw.githubusercontent.com/multidimensionalcats/kanban-mcp/main/install.sh | bash -s -- --autoIf your human specifically wants MySQL/MariaDB, add --mysql:
# MySQL via Docker:
curl -fsSL https://raw.githubusercontent.com/multidimensionalcats/kanban-mcp/main/install.sh | bash -s -- --auto --mysql --docker
# Local MySQL (set MYSQL_ROOT_PASSWORD if needed):
curl -fsSL https://raw.githubusercontent.com/multidimensionalcats/kanban-mcp/main/install.sh | bash -s -- --auto --mysql
# Remote MySQL:
curl -fsSL https://raw.githubusercontent.com/multidimensionalcats/kanban-mcp/main/install.sh | bash -s -- --auto --mysql --db-host HOSTFor Windows (PowerShell — downloaded to a file because irm | iex doesn't support passing flags like -Auto):
irm https://raw.githubusercontent.com/multidimensionalcats/kanban-mcp/main/install.ps1 -OutFile install.ps1
.\install.ps1 -AutoThis installs pipx (if needed), installs kanban-mcp, creates the database, runs migrations, and writes config to ~/.config/kanban-mcp/.env.
2. Add MCP config
Write the config entry for whichever tool you are:
Tool | Config file | Key | Format |
Claude Code |
|
| JSON |
Claude Desktop |
|
| JSON |
Gemini CLI |
|
| JSON |
VS Code / Copilot |
|
| JSON |
Cursor |
|
| JSON |
Codex CLI |
|
| TOML |
The server entry (JSON example):
{
"kanban": {
"command": "kanban-mcp"
}
}No env block is needed — credentials are read from ~/.config/kanban-mcp/.env which the install script created in step 1.
3. Verify
kanban-cli --project /path/to/humans/project summary4. Configure hooks (recommended)
Hooks are what make you use the board automatically. Without them, you only interact with kanban-mcp when the human asks you to.
kanban-hook-session-start— Runs at session start. Reads the project directory, queries in-progress items, and injects them into the conversation so you know what's active.kanban-hook-stop— Runs at session end. Lists items still in progress and reminds you to update statuses or create a diary entry.
If your client supports hooks (Claude Code, Gemini CLI, VS Code Copilot, Copilot CLI, Cursor): resolve the absolute paths via which, read your client's hook config file, merge the kanban hook entries (preserving any existing hooks), and write back. Do not overwrite other hook entries. See the Hooks section above for per-client config formats and paths.
Entry Points
Command | Description |
| MCP server (STDIO JSON-RPC) — used by AI clients |
| Web UI on localhost:5000 ( |
| CLI for manual queries and hook scripts ( |
| Database setup wizard (see flags below) |
| Session start hook — injects active items into agent sessions |
| Session stop hook — prompts for progress updates |
kanban-setup flags
Flag | Description |
| Non-interactive mode (skip all prompts, use defaults) |
| Choose backend (default: |
| Custom SQLite database file path |
| MySQL database name (default: |
| MySQL database user (default: |
| MySQL database password (default: auto-generated) |
| MySQL database host (default: |
| MySQL database port (default: |
| MySQL root password for creating the database |
| Install semantic search Python packages |
| Start MySQL via Docker |
MCP Tools Reference
Project Management
Tool | Description |
| Set the current project context (called at session start with $PWD) |
| Get the current project context |
| Get summary of items by type and status |
| Get items in 'in_progress' status |
| Get items in 'backlog' status |
Item CRUD
Tool | Description |
| Create a new issue, todo, feature, epic, question, or diary entry |
| List items with optional type/status/tag filters |
| Get full details of a specific item |
| Edit an item's title, description, priority, complexity, and/or parent |
| Permanently delete an item |
Status Workflow
Tool | Description |
| Move item to next status in its workflow |
| Move item to previous status |
| Set item to a specific status |
| Mark item as done/closed |
| Get status change history for an item |
| Get calculated metrics: lead_time, cycle_time, time_in_each_status |
Progress Updates
Tool | Description |
| Add a progress update, optionally linked to items |
| Get the most recent update |
| Get recent updates |
Relationships & Hierarchy
Tool | Description |
| Add a relationship (blocks, depends_on, relates_to, duplicates) |
| Remove a relationship |
| Get all relationships for an item |
| Get items that block a given item |
| Set or remove parent relationship |
| Get children of an item (optional recursive) |
| Get progress stats for an epic |
Tags
Tool | Description |
| List all tags with usage counts |
| Add a tag to an item |
| Remove a tag from an item |
| Get all tags assigned to an item |
| Update tag name and/or color |
| Delete a tag from the project |
File Links & Decisions
Tool | Description |
| Link a file (or file region) to an item |
| Remove a file link |
| Get all files linked to an item |
| Add a decision record to an item |
| Get all decisions for an item |
| Delete a decision record |
Search & Export
Tool | Description |
| Full-text search across items and updates |
| Search by semantic similarity (requires |
| Find items similar to a given item, decision, or update |
| Rebuild all embeddings for the project |
| Export project data in JSON, YAML, or Markdown |
Timeline
Tool | Description |
| Activity timeline for a specific item |
| Activity timeline for the entire project |
Item Types & Workflows
Type | Workflow |
issue | backlog → todo → in_progress → review → done → closed |
feature | backlog → todo → in_progress → review → done → closed |
epic | backlog → todo → in_progress → review → done → closed |
todo | backlog → todo → in_progress → done |
question | backlog → in_progress → done |
diary | done (single state) |
Contributing
git clone https://github.com/multidimensionalcats/kanban-mcp.git
cd kanban-mcp
python3 -m venv .venv && source .venv/bin/activate
pip install -e .[dev]
# Run tests (uses in-memory SQLite by default, no setup needed)
pytest
# Run tests against MySQL (requires MySQL/MariaDB running)
KANBAN_BACKEND=mysql KANBAN_DB_HOST=localhost KANBAN_DB_USER=kanban KANBAN_DB_PASSWORD=secret KANBAN_DB_NAME=kanban_test pytest
# Run frontend JS tests (requires Node.js — optional, only touches web UI code)
npm install && npm testChangelog
See CHANGELOG.md for release notes. Check your installed version with:
pipx list | grep kanban-mcp
# or
pip show kanban-mcpLicense
Available Tools
45 toolsadd_decisionA
Add a decision record to an item.
Args: item_id: The item to attach the decision to choice: What was decided (max 200 chars) rejected_alternatives: What was rejected (max 500 chars) rationale: Brief reason for the choice (max 200 chars)
Inputs: choice (required), item_id (required), rationale, rejected_alternatives.
add_relationshipA
Add a relationship between two items.
Types: 'blocks' (source blocks target from completing), 'depends_on' (source depends on target being complete), 'relates_to' (informational), 'duplicates' (informational)
Inputs: source_id (required), target_id (required), relationship_type (required).
add_tagA
Add a tag to an item (creates tag if it doesn't exist).
Inputs: item_id (required), tag_name (required).
add_updateA
Add a progress update, optionally linked to items (comma-separated IDs).
Inputs: content (required), item_ids.
advance_statusB
Move item to next status in its workflow.
Inputs: item_id (required).
close_itemC
Mark item as done/closed.
Inputs: item_id (required).
delete_decisionC
Delete a decision record.
Inputs: decision_id (required).
delete_itemB
Permanently delete an item.
Inputs: item_id (required).
delete_tagA
Delete a tag from current project (removes from all items).
Inputs: tag_id (required).
edit_itemA
Edit an existing item's title, description, priority, complexity, and/or parent.
Note: Empty string/zero means 'don't update this field'. To clear description, use a single space. Complexity 0 means 'don't update'. Parent -1 means 'don't update', 0 means 'remove parent'.
Inputs: item_id (required), title, priority, parent_id, +2 more.
export_projectA
Export project data in JSON, YAML, or Markdown format.
Args: format: Output format - 'json', 'yaml', or 'markdown' item_type: Filter by type (issue, feature, epic, todo, diary, question) status: Filter by status (backlog, todo, in_progress, review, done, closed) item_ids: Comma-separated item IDs to export (overrides type/status filters) include_tags: Include tag data for each item (default: True) include_relationships: Include relationship data include_metrics: Include calculated metrics (lead_time, cycle_time, etc.) include_updates: Include project updates include_epic_progress: Include epic progress stats detailed: For markdown, show detailed item info instead of tables limit: Maximum items to export (default: 500)
Returns: Dict with success, format, content, and item_count
Inputs: limit, format, status, detailed, +7 more.
find_similarA
Find items similar to a given item, decision, or update.
Args: source_type: Type of source ('item', 'decision', 'update') source_id: ID of the source to find similar to limit: Maximum results (default: 5) threshold: Minimum similarity 0.0-1.0 (default: 0.0)
Returns: Dict with success, results list (excluding the source itself)
Inputs: source_id (required), source_type (required), limit, threshold.
get_active_itemsB
Get items in 'in_progress' status for context during work.
Inputs: no named parameters.
get_blocking_itemsA
Get items that block this item from being completed.
Inputs: item_id (required).
get_current_projectB
Get the current project context.
Inputs: no named parameters.
get_epic_progressA
Get progress stats for an epic: total, completed, percent, incomplete_items.
Inputs: item_id (required).
get_itemC
Get full details of a specific item.
Inputs: item_id (required).
get_item_decisionsB
Get all decisions for an item.
Inputs: item_id (required).
get_item_filesA
Get all files linked to an item.
Args: item_id: The item ID to get files for
Returns: Dict with success status and list of files
Inputs: item_id (required).
get_item_metricsA
Get calculated metrics for an item: lead_time, cycle_time, time_in_each_status, revert_count, current_age (all times in hours).
Inputs: item_id (required).
get_item_relationshipsB
Get all relationships for an item (both directions).
Inputs: item_id (required).
get_item_tagsB
Get all tags assigned to an item.
Inputs: item_id (required).
get_item_timelineA
Get activity timeline for a specific item.
Returns unified timeline of status changes, decisions, updates, and git commits.
Args: item_id: The item to get timeline for limit: Maximum entries to return (default: 100)
Returns: Dict with success, entries list (sorted by timestamp desc), entry_count
Inputs: item_id (required), limit.
get_latest_updateA
Get the most recent update for current project.
Inputs: no named parameters.
get_project_timelineA
Get activity timeline for the entire project.
Returns unified timeline of all status changes, decisions, updates, and git commits.
Args: limit: Maximum entries to return (default: 100)
Returns: Dict with success, entries list (sorted by timestamp desc), entry_count
Inputs: limit.
get_status_historyB
Get status change history for an item, ordered chronologically.
Inputs: item_id (required).
get_todosA
Get items in 'backlog' status - the todo queue for current project.
Inputs: no named parameters.
get_updatesC
Get recent updates for current project.
Inputs: limit.
link_fileA
Link a file (or file region) to an item.
Args: item_id: The item to link the file to file_path: Relative path to the file line_start: Optional starting line number line_end: Optional ending line number
Returns: Dict with success status and link_id if successful
Inputs: item_id (required), file_path (required), line_end, line_start.
list_childrenA
Get children of an item. Set recursive=True to get all descendants.
Inputs: item_id (required), recursive.
list_itemsB
List items for current project with optional type/status/tag filters.
Inputs: tags, limit, status, tag_mode, +1 more.
list_tagsA
List all tags in current project with usage counts.
Inputs: no named parameters.
new_itemA
Create a new issue, todo, feature, epic, or diary entry for current project.
Inputs: title (required), item_type (required), priority, parent_id, +2 more.
project_summaryB
Get summary of items by type and status for current project.
Inputs: no named parameters.
rebuild_embeddingsA
Rebuild all embeddings for the current project.
Args: source_types: Comma-separated types to rebuild (item,decision,update). Empty = all
Returns: Dict with success, processed count, and any errors
Inputs: source_types.
remove_relationshipB
Remove a relationship between two items.
Inputs: source_id (required), target_id (required), relationship_type (required).
remove_tagC
Remove a tag from an item.
Inputs: tag_id (required), item_id (required).
revert_statusC
Move item to previous status in its workflow.
Inputs: item_id (required).
searchA
Full-text search across items and updates in current project.
Args: query: Search query string limit: Maximum results per category (default 20)
Returns: Dict with items, updates, and total_count
Inputs: query (required), limit.
semantic_searchA
Search items, decisions, and updates by semantic similarity.
Args: query: Natural language search query limit: Maximum results to return (default: 10) source_types: Comma-separated types to search (item,decision,update). Empty = all threshold: Minimum similarity score 0.0-1.0 (default: 0.0)
Returns: Dict with success, results list (each with source_type, source_id, similarity, title/snippet)
Inputs: query (required), limit, threshold, source_types.
set_current_projectA
Set the current project context.
Called at session start with $PWD.
Inputs: project_dir (required).
set_parentA
Set or remove parent relationship. Use parent_id=0 to remove parent.
Inputs: item_id (required), parent_id (required).
set_statusC
Set item to a specific status (must be valid for item type).
Inputs: status (required), item_id (required).
unlink_fileA
Remove a file link from an item.
Args: item_id: The item to unlink the file from file_path: Relative path to the file line_start: Optional starting line number (must match to unlink) line_end: Optional ending line number (must match to unlink)
Returns: Dict with success status
Inputs: item_id (required), file_path (required), line_end, line_start.
update_tagB
Update tag name and/or color.
Inputs: tag_id (required), name, color.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 45 tools
Most tools have distinct purposes, but a few convenience functions overlap with general ones (e.g., get_todos vs list_items with status filter, close_item vs set_status). The descriptions clarify intent, but the large number of get_* tools could cause initial confusion.
Most tools follow a verb_noun pattern, but there are inconsistencies: 'new_item' vs 'add_*' verbs, 'edit_item' vs 'update_tag', 'remove_tag' vs 'delete_item', and 'project_summary' lacks a verb. The mixed conventions are still readable but not uniform.
With 45 tools, the server is heavily over-scoped for a Kanban board. Many tools are specialized (metrics, decisions, embeddings) and could be combined or removed. The sheer number overwhelms an agent's tool selection.
The tool surface covers the full lifecycle of items (CRUD, status, relationships, tags, decisions, updates, search, export) with few gaps. Minor missing features include no edit for decisions and no item type change, but these are workable.
Maintenance
Related MCP Connectors
Kanban board for teams and coding agents: manage tasks, subtasks, sprints and wiki pages via MCP.
Task & board management for AI agents + humans. Kanban, comments, digests via MCP.
Project tracker for AI agents and teams: file, claim, update and hand off tickets over MCP.
One MCP server for the services your AI needs: memory, files, Microsoft 365, kanban and more.
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceA minimal MCP server that enables AI assistants to manage a kanban issue board. It provides tools for listing, creating, updating, and deleting issues with support for both local development and team deployments.10-
- AlicenseNot gradedqualityBmaintenanceMCP server that enables AI agents to manage tasks, boards, lists, and comments on a Kanban-style project management system through JSON-RPC methods.9 npm2AGPL 3.0
- AlicenseNot gradedqualityDmaintenanceAn MCP server for tracking issues across multiple AI agent sessions, enabling agents to file, claim, complete, review, and close issues with a web UI for monitoring.MIT
- AlicenseNot gradedqualityAmaintenanceA kanban board MCP server that enables AI agents to read and write project boards through session loops, with built-in cost tracking and local-first storage.10 npm1MIT