multidimensionalcats / kanban-mcp

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. More screenshots 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 Quick Start Requires **Python 3.10+**. **Linux / macOS:** **Windows (PowerShell):** 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 (or on Windows): **Manual install (no script):** Then 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. The SQLite database is created automatically on first run — no extra setup needed. For MySQL, see Database Setup. Upgrade later with: Option 2: pip > **Note:** On modern distros (Debian 12+, Fedora 38+, Arch, Gentoo), bare is blocked by PEP 668. Use , , or prefer pipx. Option 3: From source (development) > **Note:** If PEP 668 blocks the install, use a venv: first. Be aware that hooks run via , 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 ( or choose Docker when prompted). To run the compose stack manually: • **Start the containers** (MySQL 8.0 + web UI on port 5000): Migrations run automatically on web container startup. Credentials are configurable: • **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: • **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 (or ). You do not need to run for SQLite — it is only necessary if you want a custom database path or MySQL. defaults to SQLite. To choose a custom path: > **Note:** installs the semantic search Python packages. This is only needed if you installed without initially (e.g. ). If you already installed with , you don't need this flag. Works with any backend. MySQL/MariaDB (optional) If you need MySQL/MariaDB instead of SQLite: Automated (interactive) Prompts for database name, user, password, and MySQL/MariaDB root credentials (including root password), then creates the database, runs migrations, and writes credentials to . > **Note:** On Debian/Ubuntu, installs MariaDB, which defaults to 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. Automated (non-interactive / AI agents) The flag skips all interactive prompts. Without it, will prompt for each value. > **Important:** is **required** for non-interactive use unless you are running as OS root. Socket auth ( ) 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 — set or use the manual SQL setup below. Install script reference The install scripts can be run from the repo or downloaded standalone: | Env Variable | Default | Description | |---|---|---| | | | Backend: or | | | | 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). > **Note:** On MariaDB, does not match localhost socket connections — you need both the and users. Run the migration files in order: Configuration Credentials writes database credentials to a file in the user config directory: • **Linux/macOS:** (or ) • **Windows:** All install methods (pipx, pip, source) use this same location. You can also set credentials via environment variables or your MCP client's block. **Precedence** (highest to lowest): MCP client block → she…