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. More screenshots - Persistent project tracking — issues, features, todos, epics, diary entries stored in MySQL/MariaDB - Status workflows — each item type has its own progress
Add this skill
npx mdskills install multidimensionalcats/kanban-mcpComprehensive project tracking MCP server with 40+ tools, semantic search, and excellent documentation
1# kanban-mcp23A database-backed kanban board that AI coding agents use via [MCP](https://modelcontextprotocol.io/) (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.4567<details>8<summary>More screenshots</summary>910111213</details>1415## What It Does1617- **Persistent project tracking** — issues, features, todos, epics, diary entries stored in MySQL/MariaDB18- **Status workflows** — each item type has its own progression (backlog → todo → in_progress → review → done → closed)19- **Relationships & epics** — parent/child hierarchies, blocking relationships, epic progress tracking20- **Tags, decisions, file links** — attach metadata to any item21- **Semantic search** — find similar items using local ONNX embeddings (optional; downloads [nomic-embed-text-v1.5](https://huggingface.co/nomic-ai/nomic-embed-text-v1.5) from HuggingFace on first use, ~140MB)22- **Activity timeline** — unified view of status changes, decisions, updates, and git commits23- **Export** — JSON, YAML, or Markdown output with filters24- **Web UI** — browser-based board at localhost:500025- **Session hooks** — inject active items into AI agent sessions automatically2627## Quick Start2829**Linux / macOS:**30```bash31curl -fsSL https://raw.githubusercontent.com/multidimensionalcats/kanban-mcp/main/install.sh | bash32```3334**Windows (PowerShell):**35```powershell36irm https://raw.githubusercontent.com/multidimensionalcats/kanban-mcp/main/install.ps1 | iex37```3839The install script handles everything: installs pipx and kanban-mcp, detects MySQL/MariaDB (or starts it via Docker), creates the database, runs migrations, and writes your config.4041**Already have MySQL/MariaDB running?** The fast path:4243```bash44pipx install kanban-mcp[semantic]45kanban-setup46kanban-cli --project "$(pwd)" summary47```4849## Prerequisites5051- **Python 3.10+**52- **MySQL 8.0+ or MariaDB 11+** — one of:53 - Local MySQL/MariaDB install54 - Remote MySQL/MariaDB server55 - Docker (the install script can set this up for you)56- **pipx** (recommended) — installed automatically by the install script if missing5758## Installation5960The install script is the primary install method. It detects your MySQL/MariaDB situation and walks you through setup:6162```bash63# Interactive — detects MySQL/MariaDB, offers Docker if needed, installs pipx/kanban-mcp64./install.sh6566# Non-interactive with Docker for MySQL/MariaDB67./install.sh --auto --docker6869# Non-interactive with remote MySQL/MariaDB70./install.sh --auto --db-host remote.example.com7172# Windows equivalents73.\install.ps174.\install.ps1 -Auto -Docker75.\install.ps1 -Auto -DbHost remote.example.com76```7778### Option 1: pipx (recommended)7980[pipx](https://pipx.pypa.io/) 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.8182```bash83pipx install kanban-mcp[semantic]84```8586Without semantic search (smaller install):8788```bash89pipx install kanban-mcp90```9192Upgrade later with:9394```bash95pipx upgrade kanban-mcp96```9798### Option 2: pip99100```bash101pip install --user kanban-mcp[semantic]102```103104> **Note:** On modern distros (Debian 12+, Fedora 38+, Arch, Gentoo), bare `pip install` is blocked by [PEP 668](https://peps.python.org/pep-0668/). Use `--user`, `--break-system-packages`, or prefer pipx.105106### Option 3: From source (development)107108```bash109git clone https://github.com/multidimensionalcats/kanban-mcp.git110cd kanban-mcp111pip install -e .[dev,semantic]112```113114> **Note:** If PEP 668 blocks the install, use a venv: `python3 -m venv .venv && source .venv/bin/activate` first. 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.115116### Option 4: Docker (MySQL/MariaDB + web UI)117118The install script can start MySQL/MariaDB via Docker for you (`./install.sh --docker` or choose Docker when prompted). If you prefer to run the compose stack manually:119120```bash121git clone https://github.com/multidimensionalcats/kanban-mcp.git122cd kanban-mcp123docker compose up124```125126This starts MySQL 8.0 and the web UI on port 5000. Migrations run automatically on web container startup. The database is exposed on port 3306 so the host-side MCP server can connect. The MCP server still needs a separate install (pipx or pip) since MCP clients spawn it as a subprocess.127128Credentials are configurable via environment variables:129130```bash131KANBAN_DB_USER=myuser KANBAN_DB_PASSWORD=secret docker compose up132```133134## Database Setup135136Requires **MySQL 8.0+** or **MariaDB 11+** running locally (or remotely).137138### Automated (interactive)139140```bash141kanban-setup142```143144Prompts 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`.145146> **Note:** On Debian/Ubuntu, `default-mysql-server` installs MariaDB, which defaults to `auth_socket` for 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.147148> **Note:** `kanban-setup --with-semantic` installs 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 with `kanban-mcp[semantic]`, you don't need this flag.149150### Automated (non-interactive / AI agents)151152The `--auto` flag skips all interactive prompts. Without it, `kanban-setup` will prompt for each value.153154```bash155# With root password (most common)156kanban-setup --auto --mysql-root-password rootpass157158# With explicit credentials via environment variables159KANBAN_DB_NAME=kanban KANBAN_DB_USER=kanban KANBAN_DB_PASSWORD=secret \160 MYSQL_ROOT_PASSWORD=rootpass kanban-setup --auto161162# With CLI args163kanban-setup --auto --db-name mydb --db-user myuser --db-password secret164165# Socket auth (only works when OS user matches MySQL user, e.g. running as root)166kanban-setup --auto167```168169> **Important:** `MYSQL_ROOT_PASSWORD` is **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 to `auth_socket` — set `MYSQL_ROOT_PASSWORD` or use the manual SQL setup below.170171### Install script reference172173The install scripts can be run from the repo or downloaded standalone:174175```bash176./install.sh # interactive (detects MySQL/MariaDB, offers Docker)177./install.sh --auto # non-interactive, local MySQL/MariaDB (socket auth)178MYSQL_ROOT_PASSWORD=rootpass ./install.sh --auto # non-interactive, with root password179./install.sh --auto --docker # non-interactive, Docker180./install.sh --auto --db-host HOST # non-interactive, remote181./install.sh --upgrade # upgrade existing Docker install182183.\install.ps1 # Windows interactive184.\install.ps1 -Auto # Windows non-interactive185.\install.ps1 -Auto -Docker # Windows Docker186.\install.ps1 -Auto -DbHost HOST # Windows remote187.\install.ps1 -Upgrade # upgrade existing Docker install188```189190| Env Variable | Default | Description |191|---|---|---|192| `KANBAN_DB_NAME` | `kanban` | Database name |193| `KANBAN_DB_USER` | `kanban` | Database user |194| `KANBAN_DB_PASSWORD` | *(auto-generated)* | Database password |195| `KANBAN_DB_HOST` | `localhost` | Database host |196| `KANBAN_DB_PORT` | `3306` | Database port |197| `MYSQL_ROOT_USER` | `root` | Database admin user |198| `MYSQL_ROOT_PASSWORD` | *(none — tries socket auth)* | Database admin password (**required** unless running as OS root) |199200### Manual201202Manual setup is a good alternative if database root auth is problematic (e.g. socket auth issues, restricted access).203204```sql205-- As MySQL/MariaDB root user:206CREATE DATABASE kanban CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;207CREATE USER 'kanban'@'localhost' IDENTIFIED BY 'your_password_here';208CREATE USER 'kanban'@'%' IDENTIFIED BY 'your_password_here';209GRANT ALL PRIVILEGES ON `kanban`.* TO 'kanban'@'localhost';210GRANT ALL PRIVILEGES ON `kanban`.* TO 'kanban'@'%';211FLUSH PRIVILEGES;212```213214> **Note:** On MariaDB, `'kanban'@'%'` does not match localhost socket connections — you need both the `@'localhost'` and `@'%'` users.215216Run the migration files in order:217218```bash219mysql -u kanban -p kanban < kanban_mcp/migrations/001_initial_schema.sql220mysql -u kanban -p kanban < kanban_mcp/migrations/002_add_fulltext_search.sql221mysql -u kanban -p kanban < kanban_mcp/migrations/003_add_embeddings.sql222mysql -u kanban -p kanban < kanban_mcp/migrations/004_add_cascades_and_indexes.sql223```224225## Configuration226227### Credentials228229`kanban-setup` writes database credentials to a `.env` file in the user config directory:230231- **Linux/macOS:** `~/.config/kanban-mcp/.env` (or `$XDG_CONFIG_HOME/kanban-mcp/.env`)232- **Windows:** `%APPDATA%\kanban-mcp\.env`233234All install methods (pipx, pip, source) use this same location. You can also set credentials via environment variables or your MCP client's `env` block.235236**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.237238| Variable | Required | Default | Description |239|----------|----------|---------|-------------|240| `KANBAN_DB_HOST` | No | `localhost` | Database server host |241| `KANBAN_DB_PORT` | No | `3306` | Database server port |242| `KANBAN_DB_USER` | Yes | — | Database username |243| `KANBAN_DB_PASSWORD` | Yes | — | Database password |244| `KANBAN_DB_NAME` | Yes | — | Database name |245| `KANBAN_DB_POOL_SIZE` | No | `5` | Connection pool size |246| `KANBAN_PROJECT_DIR` | No | — | Override project directory detection |247| `KANBAN_WEB_PORT` | No | `5000` | Web UI port (`kanban-web`) |248| `KANBAN_WEB_HOST` | No | `127.0.0.1` | Web UI bind address (`kanban-web`) |249250### MCP Client Setup251252The `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.253254If you need to pass credentials explicitly (e.g. the client doesn't inherit your shell environment), add an `env` block:255256```json257"env": {258 "KANBAN_DB_HOST": "localhost",259 "KANBAN_DB_USER": "kanban",260 "KANBAN_DB_PASSWORD": "your_password_here",261 "KANBAN_DB_NAME": "kanban"262}263```264265#### Claude Code266267Add to `~/.claude.json` (global) or `.mcp.json` (per-project):268269```json270{271 "mcpServers": {272 "kanban": {273 "command": "kanban-mcp"274 }275 }276}277```278279#### Claude Desktop280281Add to `~/.config/Claude/claude_desktop_config.json` (Linux) or `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS):282283```json284{285 "mcpServers": {286 "kanban": {287 "command": "kanban-mcp"288 }289 }290}291```292293#### Gemini CLI294295Add to `~/.gemini/settings.json`:296297```json298{299 "mcpServers": {300 "kanban": {301 "command": "kanban-mcp"302 }303 }304}305```306307#### VS Code / Copilot308309Add to `.vscode/mcp.json` (per-project):310311```json312{313 "servers": {314 "kanban": {315 "command": "kanban-mcp"316 }317 }318}319```320321> **Note:** VS Code uses the key `servers`, not `mcpServers`.322323#### Codex CLI324325Add to `~/.codex/config.toml`:326327```toml328[mcp_servers.kanban]329command = "kanban-mcp"330```331332#### Cursor333334Add to `.cursor/mcp.json` (per-project):335336```json337{338 "mcpServers": {339 "kanban": {340 "command": "kanban-mcp"341 }342 }343}344```345346#### Other MCP Clients347348For any other MCP-compatible tool: point it at the `kanban-mcp` command with STDIO transport. If the tool can't read the `.env` file (e.g. it doesn't inherit your shell environment), pass the four `KANBAN_DB_*` variables via the client's env configuration.349350### Hooks351352Hooks are what make the agent use the board automatically. Without them, the agent only interacts with kanban-mcp when you explicitly ask it to.353354Two hooks ship as console scripts, installed alongside `kanban-mcp`:355356**`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.357358**`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.359360Both hooks exit silently if the project isn't tracked or the database is unreachable — they never block a session.361362#### Which clients support hooks?363364| Client | Session hooks? | Config location |365|--------|---------------|-----------------|366| Claude Code | Yes | `~/.claude/settings.json` |367| Gemini CLI | Yes | `~/.gemini/settings.json` |368| VS Code Copilot | Yes (preview) | `~/.claude/settings.json`¹ or `.github/hooks/*.json` |369| Copilot CLI | Yes | Hook config files |370| Cursor | Yes (plugin primitive) | Hook config |371372¹ VS Code Copilot reads Claude Code's hook configuration — if you already configured hooks for Claude Code, VS Code Copilot will use them too.373374Claude 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.375376#### Configuration377378Hooks run via `/bin/sh` (Linux/macOS) or `cmd` (Windows), which do **not** read shell profiles — you must use absolute paths.379380Find your paths:381```bash382# Linux/macOS383which kanban-hook-session-start # typically ~/.local/bin/kanban-hook-session-start384which kanban-hook-stop385```386```powershell387# Windows388Get-Command kanban-hook-session-start | Select-Object -ExpandProperty Source389# typically C:\Users\<you>\pipx\venvs\kanban-mcp\Scripts\kanban-hook-session-start.exe390```391392Merge into your client's settings file (`~/.claude/settings.json` for Claude Code and VS Code Copilot, `~/.gemini/settings.json` for Gemini CLI):393394Linux/macOS:395```json396{397 "hooks": {398 "SessionStart": [399 { "hooks": [{ "type": "command", "command": "/home/you/.local/bin/kanban-hook-session-start" }] }400 ],401 "Stop": [402 { "hooks": [{ "type": "command", "command": "/home/you/.local/bin/kanban-hook-stop" }] }403 ]404 }405}406```407408Windows:409```json410{411 "hooks": {412 "SessionStart": [413 { "hooks": [{ "type": "command", "command": "C:\\Users\\you\\pipx\\venvs\\kanban-mcp\\Scripts\\kanban-hook-session-start.exe" }] }414 ],415 "Stop": [416 { "hooks": [{ "type": "command", "command": "C:\\Users\\you\\pipx\\venvs\\kanban-mcp\\Scripts\\kanban-hook-stop.exe" }] }417 ]418 }419}420```421422If you already have hooks configured, add the kanban entries to your existing arrays — don't replace them.423424> **Tip:** `install.sh` and `install.ps1` print a ready-to-use config snippet with your resolved paths after setup completes.425426## Usage427428### First session429430Once installed and configured, open your AI agent in a project directory. The first time you do this:4314321. The session start hook fires but exits silently (it doesn't know about this project yet)4332. The agent needs to call `set_current_project` with your working directory's **absolute path** — this auto-creates the project in the database4343. From this point, all kanban tools work against this project4354. At session end, the stop hook lists any in-progress items and suggests logging progress436437On 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.438439There 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.440441> **Important:** `set_current_project` hashes the directory path as-is to identify the project. Always pass the absolute path (e.g. `/home/you/my-project`), not a relative path like `.` — relative paths will create a different project entry.442443### Three interfaces444445kanban-mcp provides three ways to interact with the same data:446447**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.448449**Web UI** — a browser-based kanban board for humans.450451```bash452kanban-web # http://127.0.0.1:5000453kanban-web --port 8080 # custom port454kanban-web --host 0.0.0.0 # network-accessible (no auth — use with care)455KANBAN_WEB_PORT=8080 kanban-web # port via env var456```457458> **macOS note:** Port 5000 is used by AirPlay Receiver on modern macOS. If `kanban-web` fails to bind, use `--port 5001` or set `KANBAN_WEB_PORT=5001`.459460The 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.461462**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}`.463464### CLI reference465466All commands take `--project PATH` with the **absolute path** to your project directory, and an optional `--format {text,json}`.467468```bash469# What's currently being worked on?470kanban-cli --project /path/to/project active471472# What's in the backlog?473kanban-cli --project /path/to/project todos474475# Project overview — counts by type and status476kanban-cli --project /path/to/project summary477478# Search items and updates479kanban-cli --project /path/to/project search "authentication"480481# Semantic search (requires [semantic] extra)482kanban-cli --project /path/to/project semantic-search "auth problems" --limit 5483484# Export the full board485kanban-cli --project /path/to/project export --format markdown486kanban-cli --project /path/to/project export --format json --metrics --relationships487488# Get children of an epic489kanban-cli --project /path/to/project children 42 --recursive490491# Context dump (what the session hooks use internally)492kanban-cli --project /path/to/project context493494# Rebuild embeddings after bulk changes495kanban-cli --project /path/to/project rebuild-embeddings496```497498> **Tip:** Paths are resolved (symlinks, `.`, `..`) before hashing, so `--project .` and `--project $PWD` refer to the same project.499500## Upgrading501502Database migrations run automatically on startup — no manual migration step needed after upgrading.503504**pipx:**505```bash506pipx upgrade kanban-mcp507```508509**pip:**510```bash511pip install --user --upgrade kanban-mcp512```513514**From source:**515```bash516cd kanban-mcp && git pull && pip install -e .[dev,semantic]517```518519**Docker:**520```bash521./install.sh --upgrade522# Windows: .\install.ps1 -Upgrade523```524525This re-downloads the latest Docker files, rebuilds the web image from PyPI, and restarts the containers. Migrations run automatically on container startup.526527## For AI Coding Agents528529**Claude, Gemini, GPT, Codex, and other agents: start here.**530531If your human has asked you to install kanban-mcp, follow these steps exactly. Do not improvise. The `--auto` flag handles all prompts.532533### 1. Install and set up the database534535Ask your human whether MySQL/MariaDB is already running locally, or whether to use Docker. Then run the appropriate one-liner:536537```bash538# Local MySQL/MariaDB (socket auth or set MYSQL_ROOT_PASSWORD):539curl -fsSL https://raw.githubusercontent.com/multidimensionalcats/kanban-mcp/main/install.sh | bash -s -- --auto540541# No database — use Docker:542curl -fsSL https://raw.githubusercontent.com/multidimensionalcats/kanban-mcp/main/install.sh | bash -s -- --auto --docker543544# Remote MySQL/MariaDB:545curl -fsSL https://raw.githubusercontent.com/multidimensionalcats/kanban-mcp/main/install.sh | bash -s -- --auto --db-host HOST546```547548Set `MYSQL_ROOT_PASSWORD` before running if the database root user uses password auth.549550For Windows (PowerShell):551```powershell552irm https://raw.githubusercontent.com/multidimensionalcats/kanban-mcp/main/install.ps1 -OutFile install.ps1553.\install.ps1 -Auto554```555556This installs pipx (if needed), installs kanban-mcp, creates the database, runs migrations, and writes credentials to `~/.config/kanban-mcp/.env`.557558### 2. Add MCP config559560Write the config entry for whichever tool you are:561562| Tool | Config file | Key | Format |563|------|-------------|-----|--------|564| Claude Code | `.mcp.json` (project) or `~/.claude.json` (global) | `mcpServers` | JSON |565| Claude Desktop | `~/.config/Claude/claude_desktop_config.json` | `mcpServers` | JSON |566| Gemini CLI | `~/.gemini/settings.json` | `mcpServers` | JSON |567| VS Code / Copilot | `.vscode/mcp.json` | `servers` | JSON |568| Cursor | `.cursor/mcp.json` | `mcpServers` | JSON |569| Codex CLI | `~/.codex/config.toml` | `[mcp_servers.kanban]` | TOML |570571The server entry (JSON example):572573```json574{575 "kanban": {576 "command": "kanban-mcp"577 }578}579```580581No `env` block is needed — credentials are read from `~/.config/kanban-mcp/.env` which the install script created in step 1.582583### 3. Verify584585```bash586kanban-cli --project /path/to/humans/project summary587```588589### 4. Configure hooks (recommended)590591Hooks are what make you use the board automatically. Without them, you only interact with kanban-mcp when the human asks you to.592593- **`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.594- **`kanban-hook-stop`** — Runs at session end. Lists items still in progress and reminds you to update statuses or create a diary entry.595596If 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](#hooks) section above for per-client config formats and paths.597598## Entry Points599600| Command | Description |601|---------|-------------|602| `kanban-mcp` | MCP server (STDIO JSON-RPC) — used by AI clients |603| `kanban-web` | Web UI on localhost:5000 (`--port`, `--host`, `--debug` flags; env: `KANBAN_WEB_PORT`, `KANBAN_WEB_HOST`) |604| `kanban-cli` | CLI for manual queries and hook scripts (`--project`, `--format` flags) |605| `kanban-setup` | Database setup wizard (`--auto` for non-interactive, `--with-semantic`) |606| `kanban-hook-session-start` | Session start hook — injects active items into agent sessions |607| `kanban-hook-stop` | Session stop hook — prompts for progress updates |608609## MCP Tools Reference610611### Project Management612613| Tool | Description |614|------|-------------|615| `set_current_project` | Set the current project context (called at session start with $PWD) |616| `get_current_project` | Get the current project context |617| `project_summary` | Get summary of items by type and status |618| `get_active_items` | Get items in 'in_progress' status |619| `get_todos` | Get items in 'backlog' status — the todo queue |620621### Item CRUD622623| Tool | Description |624|------|-------------|625| `new_item` | Create a new issue, todo, feature, epic, or diary entry |626| `list_items` | List items with optional type/status/tag filters |627| `get_item` | Get full details of a specific item |628| `edit_item` | Edit an item's title, description, priority, complexity, and/or parent |629| `delete_item` | Permanently delete an item |630631### Status Workflow632633| Tool | Description |634|------|-------------|635| `advance_status` | Move item to next status in its workflow |636| `revert_status` | Move item to previous status |637| `set_status` | Set item to a specific status |638| `close_item` | Mark item as done/closed |639| `get_status_history` | Get status change history for an item |640| `get_item_metrics` | Get calculated metrics: lead_time, cycle_time, time_in_each_status |641642### Progress Updates643644| Tool | Description |645|------|-------------|646| `add_update` | Add a progress update, optionally linked to items |647| `get_latest_update` | Get the most recent update |648| `get_updates` | Get recent updates |649650### Relationships & Hierarchy651652| Tool | Description |653|------|-------------|654| `add_relationship` | Add a relationship (blocks, depends_on, relates_to, duplicates) |655| `remove_relationship` | Remove a relationship |656| `get_item_relationships` | Get all relationships for an item |657| `get_blocking_items` | Get items that block a given item |658| `set_parent` | Set or remove parent relationship |659| `list_children` | Get children of an item (optional recursive) |660| `get_epic_progress` | Get progress stats for an epic |661662### Tags663664| Tool | Description |665|------|-------------|666| `list_tags` | List all tags with usage counts |667| `add_tag` | Add a tag to an item |668| `remove_tag` | Remove a tag from an item |669| `get_item_tags` | Get all tags assigned to an item |670| `update_tag` | Update tag name and/or color |671| `delete_tag` | Delete a tag from the project |672673### File Links & Decisions674675| Tool | Description |676|------|-------------|677| `link_file` | Link a file (or file region) to an item |678| `unlink_file` | Remove a file link |679| `get_item_files` | Get all files linked to an item |680| `add_decision` | Add a decision record to an item |681| `get_item_decisions` | Get all decisions for an item |682| `delete_decision` | Delete a decision record |683684### Search & Export685686| Tool | Description |687|------|-------------|688| `search` | Full-text search across items and updates |689| `semantic_search` | Search by semantic similarity (requires `[semantic]` extra) |690| `find_similar` | Find items similar to a given item, decision, or update |691| `rebuild_embeddings` | Rebuild all embeddings for the project |692| `export_project` | Export project data in JSON, YAML, or Markdown |693694### Timeline695696| Tool | Description |697|------|-------------|698| `get_item_timeline` | Activity timeline for a specific item |699| `get_project_timeline` | Activity timeline for the entire project |700701## Item Types & Workflows702703| Type | Workflow |704|------|----------|705| issue | backlog → todo → in_progress → review → done → closed |706| feature | backlog → todo → in_progress → review → done → closed |707| epic | backlog → todo → in_progress → review → done → closed |708| todo | backlog → todo → in_progress → done |709| question | backlog → in_progress → done |710| diary | done (single state) |711712## Contributing713714```bash715git clone https://github.com/multidimensionalcats/kanban-mcp.git716cd kanban-mcp717python3 -m venv .venv && source .venv/bin/activate718pip install -e .[dev,semantic]719720# Run Python tests (requires MySQL/MariaDB with test DB configured)721pytest722723# Run frontend JS tests (requires Node.js — optional, only touches web UI code)724npm install && npm test725```726727## License728729[MIT](LICENSE)730
Full transparency — inspect the skill content before installing.