Skip to content
Back to search

kanban-mcp

MCP server for project management with kanban boards, semantic search, and web UI

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/multidimensionalcats--kanban-mcp/badge.svg)](/listings/multidimensionalcats--kanban-mcp)

HTML

<a href="/listings/multidimensionalcats--kanban-mcp"><img src="/api/listings/multidimensionalcats--kanban-mcp/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

These steps run a script from the network that findsafeskills does not scan.

Requires **Python 3.10+**.

**Linux / macOS:**

curl -fsSL https://raw.githubusercontent.com/multidimensionalcats/kanban-mcp/main/install.sh | bash

**Windows (PowerShell):**

irm https://raw.githubusercontent.com/multidimensionalcats/kanban-mcp/main/install.ps1 | iex

The 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 --mysql

**Manual install (no script):**

pipx install kanban-mcp
kanban-cli --project "$(pwd)" summary   # SQLite DB auto-created on first run

Then add the MCP server to your AI client — see [MCP Client Setup](#mcp-client-setup).

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 783 lines · 8 findings marked

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # kanban-mcp
  2. A 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.
  3. ![Kanban board overview](webui.png)
  4. <details>
  5. <summary>More screenshots</summary>
  6. ![Activity timeline](webui-timeline.png)
  7. ![New item dialog](webui-issue.png)
  8. </details>
  9. ## What It Does
  10. - **Persistent project tracking** — issues, features, todos, epics, questions, diary entries stored in SQLite (default) or MySQL/MariaDB
  11. - **Status workflows** — each item type has its own progression (backlog → todo → in_progress → review → done → closed)
  12. - **Relationships & epics** — parent/child hierarchies, blocking relationships, epic progress tracking
  13. - **Tags, decisions, file links** — attach metadata to any item
  14. - **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 — the first query will block until download completes)
  15. - **Activity timeline** — unified view of status changes, decisions, updates, and git commits
  16. - **Export** — JSON, YAML, or Markdown output with filters
  17. - **Web UI** — browser-based board at localhost:5000
  18. - **Session hooks** — inject active items into AI agent sessions automatically
  19. ## Quick Start
  20. Requires **Python 3.10+**.
  21. **Linux / macOS:**
  22. ```bash
  23. curl -fsSL https://raw.githubusercontent.com/multidimensionalcats/kanban-mcp/main/install.sh | bash
    • Note: Pipes a downloaded script directly into a shell (curl | sh / wget | bash)
    • Line 33 on GitHub
  24. ```
  25. **Windows (PowerShell):**
  26. ```powershell
  27. irm https://raw.githubusercontent.com/multidimensionalcats/kanban-mcp/main/install.ps1 | iex
  28. ```
  29. The script prompts interactively (backend choice, etc.) then installs pipx
  30. and kanban-mcp, sets up the database, runs migrations, and prints your MCP
  31. config. SQLite is the default — just press Enter. No database server required.
  32. **Want MySQL/MariaDB instead?** Add `--mysql` (or `-MySQL` on Windows):
  33. ```bash
  34. curl -fsSL https://raw.githubusercontent.com/multidimensionalcats/kanban-mcp/main/install.sh | bash -s -- --auto --mysql
    • Note: Pipes a downloaded script directly into a shell (curl | sh / wget | bash)
    • Line 47 on GitHub
  35. ```
  36. **Manual install (no script):**
  37. ```bash
  38. pipx install kanban-mcp
  39. kanban-cli --project "$(pwd)" summary # SQLite DB auto-created on first run
  40. ```
  41. Then add the MCP server to your AI client — see [MCP Client Setup](#mcp-client-setup).
  42. ## Prerequisites
  43. - **Python 3.10+**
  44. - **pipx** (recommended) — installed automatically by the install script if missing
  45. - **MySQL 8.0+ or MariaDB 11+** *(optional)* — only needed if you choose MySQL over the default SQLite backend
  46. ## Installation
  47. The [Quick Start](#quick-start) one-liner is the fastest path. Below are alternative install methods and additional options.
  48. ### Option 1: pipx (recommended)
  49. [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.
  50. ```bash
  51. # SQLite backend (default, zero dependencies)
  52. pipx install kanban-mcp
  53. # With semantic search
  54. pipx install kanban-mcp[semantic]
  55. # With MySQL backend
  56. pipx install kanban-mcp[mysql]
  57. # Everything (MySQL + semantic)
  58. pipx install kanban-mcp[full]
  59. ```
  60. The SQLite database is created automatically on first run — no extra setup needed. For MySQL, see [Database Setup](#database-setup).
  61. Upgrade later with:
  62. ```bash
  63. pipx upgrade kanban-mcp
  64. ```
  65. ### Option 2: pip
  66. ```bash
  67. pip install --user kanban-mcp
  68. ```
  69. > **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.
  70. ### Option 3: From source (development)
  71. ```bash
  72. git clone https://github.com/multidimensionalcats/kanban-mcp.git
  73. cd kanban-mcp
  74. pip install -e .[dev]
  75. ```
  76. > **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.
  77. ### Option 4: Docker (MySQL/MariaDB + web UI)
  78. > **Note:** Docker compose runs MySQL/MariaDB, not SQLite. Use this if you want a containerized MySQL setup.
  79. 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:
  80. 1. **Start the containers** (MySQL 8.0 + web UI on port 5000):
  81. ```bash
  82. git clone https://github.com/multidimensionalcats/kanban-mcp.git
  83. cd kanban-mcp
  84. docker compose up
  85. ```
  86. Migrations run automatically on web container startup. Credentials are configurable: `KANBAN_DB_USER=myuser KANBAN_DB_PASSWORD=secret docker compose up`
  87. 2. **Install 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:
  88. ```bash
  89. pipx install kanban-mcp[mysql]
  90. ```
  91. 3. **Configure your MCP client** — see [MCP Client Setup](#mcp-client-setup). The database is exposed on port 3306 so the host-side MCP server can connect.
  92. ## Database Setup
  93. kanban-mcp uses **SQLite by default** — no setup required. The database
  94. file is created automatically on first run at `~/.local/share/kanban-mcp/kanban.db`
  95. (or `$XDG_DATA_HOME/kanban-mcp/kanban.db`). You do not need to run `kanban-setup`
  96. for SQLite — it is only necessary if you want a custom database path or MySQL.
  97. `kanban-setup --auto` defaults to SQLite. To choose a custom path:
  98. ```bash
  99. kanban-setup --auto --backend sqlite --sqlite-path /path/to/db
  100. ```
  101. > **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. Works with any backend.
  102. ### MySQL/MariaDB (optional)
  103. If you need MySQL/MariaDB instead of SQLite:
  104. #### Automated (interactive)
  105. ```bash
  106. kanban-setup
  107. ```
  108. Prompts 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`.
  109. > **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.
  110. #### Automated (non-interactive / AI agents)
  111. The `--auto` flag skips all interactive prompts. Without it, `kanban-setup` will prompt for each value.
  112. ```bash
  113. # With root password (most common)
  114. kanban-setup --auto --backend mysql --mysql-root-password rootpass
  115. # With explicit credentials via environment variables
  116. KANBAN_DB_NAME=kanban KANBAN_DB_USER=kanban KANBAN_DB_PASSWORD=secret \
  117. MYSQL_ROOT_PASSWORD=rootpass kanban-setup --auto --backend mysql
  118. # With CLI args
  119. kanban-setup --auto --backend mysql --db-name mydb --db-user myuser --db-password secret
  120. # Socket auth (only works when OS user matches MySQL user, e.g. running as root)
  121. kanban-setup --auto --backend mysql
  122. ```
  123. > **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.
  124. ### Install script reference
  125. The install scripts can be run from the repo or downloaded standalone:
  126. ```bash
  127. ./install.sh # interactive (asks backend, installs pipx/kanban-mcp)
  128. ./install.sh --auto # non-interactive, SQLite (default, zero config)
  129. ./install.sh --auto --mysql # non-interactive, local MySQL/MariaDB (socket auth)
  130. MYSQL_ROOT_PASSWORD=rootpass ./install.sh --auto --mysql # non-interactive, MySQL with root password
  131. ./install.sh --auto --mysql --docker # non-interactive, MySQL via Docker
  132. ./install.sh --auto --mysql --db-host HOST # non-interactive, remote MySQL
  133. ./install.sh --upgrade # upgrade existing Docker install
  134. .\install.ps1 # Windows interactive
  135. .\install.ps1 -Auto # Windows non-interactive (SQLite)
  136. .\install.ps1 -Auto -MySQL # Windows MySQL
  137. .\install.ps1 -Auto -MySQL -Docker # Windows MySQL via Docker
  138. .\install.ps1 -Auto -MySQL -DbHost HOST # Windows remote MySQL
  139. .\install.ps1 -Upgrade # upgrade existing Docker install
  140. ```
  141. | Env Variable | Default | Description |
  142. |---|---|---|
  143. | `KANBAN_BACKEND` | `sqlite` | Backend: `sqlite` or `mysql` |
  144. | `KANBAN_SQLITE_PATH` | `$XDG_DATA_HOME/kanban-mcp/kanban.db` | SQLite database file path |
  145. | `KANBAN_DB_NAME` | `kanban` | MySQL database name |
  146. | `KANBAN_DB_USER` | `kanban` | Database user |
  147. | `KANBAN_DB_PASSWORD` | *(auto-generated)* | Database password |
  148. | `KANBAN_DB_HOST` | `localhost` | Database host |
  149. | `KANBAN_DB_PORT` | `3306` | Database port |
  150. | `MYSQL_ROOT_USER` | `root` | Database admin user |
  151. | `MYSQL_ROOT_PASSWORD` | *(none — tries socket auth)* | Database admin password (**required** unless running as OS root) |
  152. #### Manual
  153. Manual setup is a good alternative if database root auth is problematic (e.g. socket auth issues, restricted access).
  154. ```sql
  155. -- As MySQL/MariaDB root user:
  156. CREATE DATABASE kanban CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
  157. CREATE USER 'kanban'@'localhost' IDENTIFIED BY 'your_password_here';
  158. CREATE USER 'kanban'@'%' IDENTIFIED BY 'your_password_here';
  159. GRANT ALL PRIVILEGES ON `kanban`.* TO 'kanban'@'localhost';
  160. GRANT ALL PRIVILEGES ON `kanban`.* TO 'kanban'@'%';
  161. FLUSH PRIVILEGES;
  162. ```
  163. > **Note:** On MariaDB, `'kanban'@'%'` does not match localhost socket connections — you need both the `@'localhost'` and `@'%'` users.
  164. Run the migration files in order:
  165. ```bash
  166. mysql -u kanban -p kanban < kanban_mcp/migrations/001_initial_schema.sql
  167. mysql -u kanban -p kanban < kanban_mcp/migrations/002_add_fulltext_search.sql
  168. mysql -u kanban -p kanban < kanban_mcp/migrations/003_add_embeddings.sql
  169. mysql -u kanban -p kanban < kanban_mcp/migrations/004_add_cascades_and_indexes.sql
  170. ```
  171. ## Configuration
  172. ### Credentials
  173. `kanban-setup` writes database credentials to a `.env` file in the user config directory:
  174. - **Linux/macOS:** `~/.config/kanban-mcp/.env` (or `$XDG_CONFIG_HOME/kanban-mcp/.env`)
  175. - **Windows:** `%APPDATA%\kanban-mcp\.env`
  176. 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.
  177. **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.
  178. > **Warning:** If you previously used MySQL and switch to SQLite, remove or rename the old `.env` file at `~/.config/kanban-mcp/.env`. Leftover `KANBAN_DB_USER`/`KANBAN_DB_PASSWORD`/`KANBAN_DB_NAME` values will silently trigger MySQL auto-detection. Alternatively, set `KANBAN_BACKEND=sqlite` explicitly to override.
  179. | Variable | Required | Default | Description |
  180. |----------|----------|---------|-------------|
  181. | `KANBAN_BACKEND` | No | *(auto-detect)* | Force backend: `sqlite` or `mysql`. Auto-detect uses MySQL if `KANBAN_DB_USER`, `KANBAN_DB_PASSWORD`, and `KANBAN_DB_NAME` are all set, otherwise SQLite |
  182. | `KANBAN_SQLITE_PATH` | No | `$XDG_DATA_HOME/kanban-mcp/kanban.db` | SQLite database file path |
  183. | `KANBAN_DB_HOST` | No | `localhost` | MySQL database server host |
  184. | `KANBAN_DB_PORT` | No | `3306` | MySQL database server port |
  185. | `KANBAN_DB_USER` | Yes (MySQL only) | — | MySQL database username |
  186. | `KANBAN_DB_PASSWORD` | Yes (MySQL only) | — | MySQL database password |
  187. | `KANBAN_DB_NAME` | Yes (MySQL only) | — | MySQL database name |
  188. | `KANBAN_DB_POOL_SIZE` | No | `5` | MySQL connection pool size |
  189. | `KANBAN_PROJECT_DIR` | No | — | Override project directory detection |
  190. | `KANBAN_WEB_PORT` | No | `5000` | Web UI port (`kanban-web`) |
  191. | `KANBAN_WEB_HOST` | No | `127.0.0.1` | Web UI bind address (`kanban-web`) |
  192. ### MCP Client Setup
  193. 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.
  194. If you need to pass credentials explicitly (e.g. the client doesn't inherit your shell environment), add an `env` block:
  195. ```json
  196. "env": {
  197. "KANBAN_DB_HOST": "localhost",
  198. "KANBAN_DB_USER": "kanban",
  199. "KANBAN_DB_PASSWORD": "your_password_here",
  200. "KANBAN_DB_NAME": "kanban"
  201. }
  202. ```
  203. #### Claude Code
  204. Add to `~/.claude.json` (global) or `.mcp.json` (per-project):
  205. ```json
  206. {
  207. "mcpServers": {
  208. "kanban": {
  209. "command": "kanban-mcp"
  210. }
  211. }
  212. }
  213. ```
  214. #### Claude Desktop
  215. Add to `~/.config/Claude/claude_desktop_config.json` (Linux) or `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS):
  216. ```json
  217. {
  218. "mcpServers": {
  219. "kanban": {
  220. "command": "kanban-mcp"
  221. }
  222. }
  223. }
  224. ```
  225. #### Gemini CLI
  226. Add to `~/.gemini/settings.json`:
  227. ```json
  228. {
  229. "mcpServers": {
  230. "kanban": {
  231. "command": "kanban-mcp"
  232. }
  233. }
  234. }
  235. ```
  236. #### VS Code / Copilot
  237. Add to `.vscode/mcp.json` (per-project):
  238. ```json
  239. {
  240. "servers": {
  241. "kanban": {
  242. "command": "kanban-mcp"
  243. }
  244. }
  245. }
  246. ```
  247. > **Note:** VS Code uses the key `servers`, not `mcpServers`.
  248. #### Codex CLI
  249. Add to `~/.codex/config.toml`:
  250. ```toml
  251. [mcp_servers.kanban]
  252. command = "kanban-mcp"
  253. ```
  254. #### Cursor
  255. Add to `.cursor/mcp.json` (per-project):
  256. ```json
  257. {
  258. "mcpServers": {
  259. "kanban": {
  260. "command": "kanban-mcp"
  261. }
  262. }
  263. }
  264. ```
  265. #### Other MCP Clients
  266. 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.
  267. ### Hooks
  268. 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.
  269. Two hooks ship as console scripts, installed alongside `kanban-mcp`:
  270. **`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.
  271. **`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.
  272. Both hooks exit silently if the project isn't tracked or the database is unreachable — they never block a session.
  273. #### Which clients support hooks?
  274. | Client | Session hooks? | Config location |
  275. |--------|---------------|-----------------|
  276. | Claude Code | Yes | `~/.claude/settings.json` |
  277. | Gemini CLI | Yes | `~/.gemini/settings.json` |
  278. | VS Code Copilot | Yes (preview) | `~/.claude/settings.json`¹ or `.github/hooks/*.json` |
  279. | Copilot CLI | Yes | Hook config files |
  280. | Cursor | Yes (plugin primitive) | Hook config |
  281. ¹ VS Code Copilot reads Claude Code's hook configuration — if you already configured hooks for Claude Code, VS Code Copilot will use them too.
  282. 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.
  283. #### Configuration
  284. Hooks run via `/bin/sh` (Linux/macOS) or `cmd` (Windows), which do **not** read shell profiles — you must use absolute paths.
  285. Find your paths:
  286. ```bash
  287. # Linux/macOS
  288. which kanban-hook-session-start # typically ~/.local/bin/kanban-hook-session-start
  289. which kanban-hook-stop
  290. ```
  291. ```powershell
  292. # Windows
  293. Get-Command kanban-hook-session-start | Select-Object -ExpandProperty Source
  294. # typically C:\Users\<you>\pipx\venvs\kanban-mcp\Scripts\kanban-hook-session-start.exe
  295. ```
  296. Merge into your client's settings file (`~/.claude/settings.json` for Claude Code and VS Code Copilot, `~/.gemini/settings.json` for Gemini CLI):
  297. Linux/macOS:
  298. ```json
  299. {
  300. "hooks": {
  301. "SessionStart": [
  302. { "hooks": [{ "type": "command", "command": "/home/you/.local/bin/kanban-hook-session-start" }] }
  303. ],
  304. "Stop": [
  305. { "hooks": [{ "type": "command", "command": "/home/you/.local/bin/kanban-hook-stop" }] }
  306. ]
  307. }
  308. }
  309. ```
  310. Windows:
  311. ```json
  312. {
  313. "hooks": {
  314. "SessionStart": [
  315. { "hooks": [{ "type": "command", "command": "C:\\Users\\you\\pipx\\venvs\\kanban-mcp\\Scripts\\kanban-hook-session-start.exe" }] }
  316. ],
  317. "Stop": [
  318. { "hooks": [{ "type": "command", "command": "C:\\Users\\you\\pipx\\venvs\\kanban-mcp\\Scripts\\kanban-hook-stop.exe" }] }
  319. ]
  320. }
  321. }
  322. ```
  323. If you already have hooks configured, add the kanban entries to your existing arrays — don't replace them.
  324. > **Tip:** `install.sh` and `install.ps1` print a ready-to-use config snippet with your resolved paths after setup completes.
  325. ## Usage
  326. ### First session
  327. Once installed and configured, open your AI agent in a project directory. The first time you do this:
  328. 1. The session start hook fires but exits silently (it doesn't know about this project yet)
  329. 2. The agent needs to call `set_current_project` with your working directory's **absolute path** — this auto-creates the project in the database
  330. 3. From this point, all kanban tools work against this project
  331. 4. At session end, the stop hook lists any in-progress items and suggests logging progress
  332. 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.
  333. 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.
  334. > **Note:** Paths are resolved (symlinks, `.`, `..`) before hashing, so `--project .` and `--project $PWD` refer to the same project. The same applies to `set_current_project`.
  335. ### Three interfaces
  336. kanban-mcp provides three ways to interact with the same data:
  337. **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.
  338. **Web UI** — a browser-based kanban board for humans.
  339. ```bash
  340. kanban-web # http://127.0.0.1:5000
  341. kanban-web --port 8080 # custom port
  342. kanban-web --host 0.0.0.0 # network-accessible (no auth — use with care)
  343. KANBAN_WEB_PORT=8080 kanban-web # port via env var
  344. ```
  345. `kanban-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.
  346. > **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`.
  347. 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.
  348. **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}`.
  349. ### CLI reference
  350. All commands take `--project PATH` with the **absolute path** to your project directory, and an optional `--format {text,json}`.
  351. ```bash
  352. # What's currently being worked on?
  353. kanban-cli --project /path/to/project active
  354. # What's in the backlog?
  355. kanban-cli --project /path/to/project todos
  356. # Project overview — counts by type and status
  357. kanban-cli --project /path/to/project summary
  358. # Search items and updates
  359. kanban-cli --project /path/to/project search "authentication"
  360. # Semantic search (requires [semantic] extra)
  361. kanban-cli --project /path/to/project semantic-search "auth problems" --limit 5
  362. # Export the full board
  363. kanban-cli --project /path/to/project export --format markdown
  364. kanban-cli --project /path/to/project export --format json --metrics --relationships
  365. # Get children of an epic
  366. kanban-cli --project /path/to/project children 42 --recursive
  367. # Context dump (what the session hooks use internally)
  368. kanban-cli --project /path/to/project context
  369. # Rebuild embeddings after bulk changes
  370. kanban-cli --project /path/to/project rebuild-embeddings
  371. ```
  372. > **Tip:** Paths are resolved (symlinks, `.`, `..`) before hashing, so `--project .` and `--project $PWD` refer to the same project.
  373. ## Upgrading
  374. Database migrations run automatically on startup — no manual migration step needed after upgrading.
  375. **pipx:**
  376. ```bash
  377. pipx upgrade kanban-mcp
  378. ```
  379. **pip:**
  380. ```bash
  381. pip install --user --upgrade kanban-mcp
  382. ```
  383. **From source:**
  384. ```bash
  385. cd kanban-mcp && git pull && pip install -e .[dev]
  386. ```
  387. **Docker:**
  388. ```bash
  389. ./install.sh --upgrade
  390. # Windows: .\install.ps1 -Upgrade
  391. ```
  392. This re-downloads the latest Docker files, rebuilds the web image from PyPI, and restarts the containers. Migrations run automatically on container startup.
  393. ## For AI Coding Agents
  394. **Claude, Gemini, GPT, Codex, and other agents: start here.**
  395. If your human has asked you to install kanban-mcp, follow these steps exactly. Do not improvise. The `--auto` flag handles all prompts.
  396. ### 1. Install and set up the database
  397. The default path uses SQLite — zero config, no database server needed:
  398. ```bash
  399. curl -fsSL https://raw.githubusercontent.com/multidimensionalcats/kanban-mcp/main/install.sh | bash -s -- --auto
    • Note: Pipes a downloaded script directly into a shell (curl | sh / wget | bash)
    • Line 559 on GitHub
  400. ```
  401. If your human specifically wants MySQL/MariaDB, add `--mysql`:
  402. ```bash
  403. # MySQL via Docker:
  404. curl -fsSL https://raw.githubusercontent.com/multidimensionalcats/kanban-mcp/main/install.sh | bash -s -- --auto --mysql --docker
    • Note: Pipes a downloaded script directly into a shell (curl | sh / wget | bash)
    • Line 566 on GitHub
  405. # Local MySQL (set MYSQL_ROOT_PASSWORD if needed):
  406. curl -fsSL https://raw.githubusercontent.com/multidimensionalcats/kanban-mcp/main/install.sh | bash -s -- --auto --mysql
    • Note: Pipes a downloaded script directly into a shell (curl | sh / wget | bash)
    • Line 569 on GitHub
  407. # Remote MySQL:
  408. curl -fsSL https://raw.githubusercontent.com/multidimensionalcats/kanban-mcp/main/install.sh | bash -s -- --auto --mysql --db-host HOST
    • Note: Pipes a downloaded script directly into a shell (curl | sh / wget | bash)
    • Line 572 on GitHub
  409. ```
  410. For Windows (PowerShell — downloaded to a file because `irm | iex` doesn't support passing flags like `-Auto`):
  411. ```powershell
  412. irm https://raw.githubusercontent.com/multidimensionalcats/kanban-mcp/main/install.ps1 -OutFile install.ps1
  413. .\install.ps1 -Auto
  414. ```
  415. This installs pipx (if needed), installs kanban-mcp, creates the database, runs migrations, and writes config to `~/.config/kanban-mcp/.env`.
  416. ### 2. Add MCP config
  417. Write the config entry for whichever tool you are:
  418. | Tool | Config file | Key | Format |
  419. |------|-------------|-----|--------|
  420. | Claude Code | `.mcp.json` (project) or `~/.claude.json` (global) | `mcpServers` | JSON |
  421. | Claude Desktop | `~/.config/Claude/claude_desktop_config.json` | `mcpServers` | JSON |
  422. | Gemini CLI | `~/.gemini/settings.json` | `mcpServers` | JSON |
  423. | VS Code / Copilot | `.vscode/mcp.json` | `servers` | JSON |
  424. | Cursor | `.cursor/mcp.json` | `mcpServers` | JSON |
  425. | Codex CLI | `~/.codex/config.toml` | `[mcp_servers.kanban]` | TOML |
  426. The server entry (JSON example):
  427. ```json
  428. {
  429. "kanban": {
  430. "command": "kanban-mcp"
  431. }
  432. }
  433. ```
  434. No `env` block is needed — credentials are read from `~/.config/kanban-mcp/.env` which the install script created in step 1.
  435. ### 3. Verify
  436. ```bash
  437. kanban-cli --project /path/to/humans/project summary
  438. ```
  439. ### 4. Configure hooks (recommended)
  440. Hooks are what make you use the board automatically. Without them, you only interact with kanban-mcp when the human asks you to.
  441. - **`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.
  442. - **`kanban-hook-stop`** — Runs at session end. Lists items still in progress and reminds you to update statuses or create a diary entry.
  443. 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](#hooks) section above for per-client config formats and paths.
  444. ## Entry Points
  445. | Command | Description |
  446. |---------|-------------|
  447. | `kanban-mcp` | MCP server (STDIO JSON-RPC) — used by AI clients |
  448. | `kanban-web` | Web UI on localhost:5000 (`--port`, `--host`, `--debug` flags; env: `KANBAN_WEB_PORT`, `KANBAN_WEB_HOST`) |
  449. | `kanban-cli` | CLI for manual queries and hook scripts (`--project`, `--format` flags) |
  450. | `kanban-setup` | Database setup wizard (see flags below) |
  451. | `kanban-hook-session-start` | Session start hook — injects active items into agent sessions |
  452. | `kanban-hook-stop` | Session stop hook — prompts for progress updates |
  453. ### `kanban-setup` flags
  454. | Flag | Description |
  455. |------|-------------|
  456. | `--auto` | Non-interactive mode (skip all prompts, use defaults) |
  457. | `--backend {sqlite,mysql}` | Choose backend (default: `sqlite`) |
  458. | `--sqlite-path PATH` | Custom SQLite database file path |
  459. | `--db-name NAME` | MySQL database name (default: `kanban`) |
  460. | `--db-user USER` | MySQL database user (default: `kanban`) |
  461. | `--db-password PASS` | MySQL database password (default: auto-generated) |
  462. | `--db-host HOST` | MySQL database host (default: `localhost`) |
  463. | `--db-port PORT` | MySQL database port (default: `3306`) |
  464. | `--mysql-root-password PASS` | MySQL root password for creating the database |
  465. | `--with-semantic` | Install semantic search Python packages |
  466. | `--docker` | Start MySQL via Docker |
  467. ## MCP Tools Reference
  468. ### Project Management
  469. | Tool | Description |
  470. |------|-------------|
  471. | `set_current_project` | Set the current project context (called at session start with $PWD) |
  472. | `get_current_project` | Get the current project context |
  473. | `project_summary` | Get summary of items by type and status |
  474. | `get_active_items` | Get items in 'in_progress' status |
  475. | `get_todos` | Get items in 'backlog' status |
  476. ### Item CRUD
  477. | Tool | Description |
  478. |------|-------------|
  479. | `new_item` | Create a new issue, todo, feature, epic, question, or diary entry |
  480. | `list_items` | List items with optional type/status/tag filters |
  481. | `get_item` | Get full details of a specific item |
  482. | `edit_item` | Edit an item's title, description, priority, complexity, and/or parent |
  483. | `delete_item` | Permanently delete an item |
  484. ### Status Workflow
  485. | Tool | Description |
  486. |------|-------------|
  487. | `advance_status` | Move item to next status in its workflow |
  488. | `revert_status` | Move item to previous status |
  489. | `set_status` | Set item to a specific status |
  490. | `close_item` | Mark item as done/closed |
  491. | `get_status_history` | Get status change history for an item |
  492. | `get_item_metrics` | Get calculated metrics: lead_time, cycle_time, time_in_each_status |
  493. ### Progress Updates
  494. | Tool | Description |
  495. |------|-------------|
  496. | `add_update` | Add a progress update, optionally linked to items |
  497. | `get_latest_update` | Get the most recent update |
  498. | `get_updates` | Get recent updates |
  499. ### Relationships & Hierarchy
  500. | Tool | Description |
  501. |------|-------------|
  502. | `add_relationship` | Add a relationship (blocks, depends_on, relates_to, duplicates) |
  503. | `remove_relationship` | Remove a relationship |
  504. | `get_item_relationships` | Get all relationships for an item |
  505. | `get_blocking_items` | Get items that block a given item |
  506. | `set_parent` | Set or remove parent relationship |
  507. | `list_children` | Get children of an item (optional recursive) |
  508. | `get_epic_progress` | Get progress stats for an epic |
  509. ### Tags
  510. | Tool | Description |
  511. |------|-------------|
  512. | `list_tags` | List all tags with usage counts |
  513. | `add_tag` | Add a tag to an item |
  514. | `remove_tag` | Remove a tag from an item |
  515. | `get_item_tags` | Get all tags assigned to an item |
  516. | `update_tag` | Update tag name and/or color |
  517. | `delete_tag` | Delete a tag from the project |
  518. ### File Links & Decisions
  519. | Tool | Description |
  520. |------|-------------|
  521. | `link_file` | Link a file (or file region) to an item |
  522. | `unlink_file` | Remove a file link |
  523. | `get_item_files` | Get all files linked to an item |
  524. | `add_decision` | Add a decision record to an item |
  525. | `get_item_decisions` | Get all decisions for an item |
  526. | `delete_decision` | Delete a decision record |
  527. ### Search & Export
  528. | Tool | Description |
  529. |------|-------------|
  530. | `search` | Full-text search across items and updates |
  531. | `semantic_search` | Search by semantic similarity (requires `[semantic]` extra) |
  532. | `find_similar` | Find items similar to a given item, decision, or update |
  533. | `rebuild_embeddings` | Rebuild all embeddings for the project |
  534. | `export_project` | Export project data in JSON, YAML, or Markdown |
  535. ### Timeline
  536. | Tool | Description |
  537. |------|-------------|
  538. | `get_item_timeline` | Activity timeline for a specific item |
  539. | `get_project_timeline` | Activity timeline for the entire project |
  540. ## Item Types & Workflows
  541. | Type | Workflow |
  542. |------|----------|
  543. | issue | backlog → todo → in_progress → review → done → closed |
  544. | feature | backlog → todo → in_progress → review → done → closed |
  545. | epic | backlog → todo → in_progress → review → done → closed |
  546. | todo | backlog → todo → in_progress → done |
  547. | question | backlog → in_progress → done |
  548. | diary | done (single state) |
  549. ## Contributing
  550. ```bash
  551. git clone https://github.com/multidimensionalcats/kanban-mcp.git
  552. cd kanban-mcp
  553. python3 -m venv .venv && source .venv/bin/activate
  554. pip install -e .[dev]
  555. # Run tests (uses in-memory SQLite by default, no setup needed)
  556. pytest
  557. # Run tests against MySQL (requires MySQL/MariaDB running)
  558. KANBAN_BACKEND=mysql KANBAN_DB_HOST=localhost KANBAN_DB_USER=kanban KANBAN_DB_PASSWORD=secret KANBAN_DB_NAME=kanban_test pytest
  559. # Run frontend JS tests (requires Node.js — optional, only touches web UI code)
  560. npm install && npm test
  561. ```
  562. ## Changelog
  563. See [CHANGELOG.md](CHANGELOG.md) for release notes. Check your installed version with:
  564. ```bash
  565. pipx list | grep kanban-mcp
  566. # or
  567. pip show kanban-mcp
  568. ```
  569. ## License
  570. [MIT](LICENSE)

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.