使用说明

看板mcp

一个数据库支持的看板，AI编码代理通过它使用主控程序（模型上下文协议）。使用面向人类的web UI和面向代理的40多种工具，跟踪所有项目中的问题、功能、待办事项、史诗和日记条目。

More screenshots

它的作用

持续项目跟踪 --问题、功能、待办事项、史诗、问题、日记条目存储在SQLite（默认）或MySQL/MariaDB中
状态工作流 --每种项目类型都有自己的进度（积压→ todo → 正在进行中→ 审查→ done → 关闭）
关系与史诗 --父/子层次结构、阻塞关系、史诗般的进度跟踪
标签、决策、文件链接 --将元数据附加到任何项目
语义搜索 --使用本地ONNX嵌入查找类似项目（可选；下载 nomic-embed-ext-v1.5 首次使用HuggingFace时，约140MB——第一个查询将被阻止，直到下载完成）
活动时间表 --状态更改、决策、更新和git提交的统一视图
出口 --带过滤器的JSON、YAML或Markdown输出
Web用户界面 --基于浏览器的本地主机板：5000
会话挂钩 --自动将活动项注入AI代理会话

快速开始

需要 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

脚本以交互方式提示（后端选择等），然后安装pipx 以及看板mcp，设置数据库，运行迁移，并打印您的mcp 配置。SQLite是默认设置——只需按Enter键。不需要数据库服务器。

想要MySQL或MariaDB吗？ 添加 --mysql （或 -MySQL 在Windows上）：

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

手动安装（无脚本）：

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

然后将MCP服务器添加到您的AI客户端中——请参阅 MCP客户端设置.

先决条件

Python 3.10+
pipx （推荐）--如果缺少，则由安装脚本自动安装
MySQL 8.0+或MariaDB 11+ （可选） --仅当您选择MySQL而不是默认SQLite后端时才需要

安装

这快速开始一条直线是最快的路径。以下是替代安装方法和其他选项。

选项1:pipx（推荐）

pipx 安装到一个隔离的virtualenv中，同时使命令全局可用。这避免了现代发行版上的PEP 668冲突，并确保钩子在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]

SQLite数据库是在第一次运行时自动创建的，不需要额外的设置。关于MySQL，请参见数据库设置.

稍后升级：

pipx upgrade kanban-mcp

选项2:pip

pip install --user kanban-mcp

注：在现代发行版（Debian 12+、Fedora 38+、Arch、Gentoo）上，裸机 pip install 被...阻挡 pep668.使用 --user, --break-system-packages，或者更喜欢pipx。

选项3：来源（开发）

git clone https://github.com/multidimensionalcats/kanban-mcp.git
cd kanban-mcp
pip install -e .[dev]

注：如果PEP 668阻止安装，请使用venv： python3 -m venv .venv && source .venv/bin/activate 第一。请注意，钩子会穿过 /bin/sh，而不是venv Python——您需要在钩子配置中使用venv控制台脚本的完整路径。

选项4：Docker（MySQL/MariaDB+web UI）

注： Docker compose运行MySQL/MariaDB，而不是SQLite。如果你想要一个容器化的MySQL设置，请使用此选项。

安装脚本可以通过Docker为您启动MySQL/MariaDB(./install.sh --auto --mysql --docker 或在提示时选择Docker）。要手动运行组合堆栈，请执行以下操作：

启动容器 （MySQL 8.0+端口5000上的web UI）：
```
git clone https://github.com/multidimensionalcats/kanban-mcp.git
cd kanban-mcp
docker compose up
```
迁移在web容器启动时自动运行。凭据是可配置的： KANBAN_DB_USER=myuser KANBAN_DB_PASSWORD=secret docker compose up
在主机上安装MCP服务器 --Docker只提供数据库和web UI。MCP客户端将服务器作为子进程生成，因此必须在本地安装：
```
pipx install kanban-mcp[mysql]
```
配置您的MCP客户端 --看 MCP客户端设置数据库暴露在端口3306上，因此主机侧MCP服务器可以连接。

数据库设置

看板mcp使用 默认情况下为SQLite --无需设置。数据库文件在首次运行时自动创建 ~/.local/share/kanban-mcp/kanban.db （或 $XDG_DATA_HOME/kanban-mcp/kanban.db).你不需要跑 kanban-setup 对于SQLite，只有当您想要自定义数据库路径或MySQL时，才需要它。

kanban-setup --auto 默认为SQLite。要选择自定义路径，请执行以下操作：

kanban-setup --auto --backend sqlite --sqlite-path /path/to/db

注： kanban-setup --with-semantic 安装语义搜索Python包。只有在没有安装的情况下才需要这样做 [semantic] 最初（例如。 pipx install kanban-mcp).如果您已经安装了 kanban-mcp[semantic]你不需要这面旗。适用于任何后端。

MySQL/MariaDB（可选）

如果你需要MySQL/MariaDB而不是SQLite：

自动化（交互式）

kanban-setup

提示输入数据库名称、用户、密码和MySQL/MariaDB根凭据（包括根密码），然后创建数据库，运行迁移，并将凭据写入 ~/.config/kanban-mcp/.env.

注：在Debian/Ubuntu上， default-mysql-server 安装MariaDB，默认为 auth_socket 对于root用户。Socket auth仅在操作系统用户与MySQL用户匹配时有效（即以操作系统根用户身份运行）。对于非root用户，在提示时提供MySQL root密码——这是正常路径。

自动化（非交互式/AI代理）

这 --auto flag跳过所有交互式提示。没有它， kanban-setup 将提示输入每个值。

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

重要提示： MYSQL_ROOT_PASSWORD 是 必需的 用于非交互式使用，除非您以操作系统根用户身份运行。套接字身份验证(auth_socket)只有当操作系统用户与MySQL用户匹配时才有效——这在CI或Docker之外并不常见。在Debian/Ubuntu上，MariaDB默认root为 auth_socket --set MYSQL_ROOT_PASSWORD 或者使用下面的手动SQL设置。

安装脚本引用

安装脚本可以从仓库运行，也可以单独下载：

./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 install

环境变量	默认值	描述
`KANBAN_BACKEND`	`sqlite`	后端： `sqlite` 或 `mysql`
`KANBAN_SQLITE_PATH`	`$XDG_DATA_HOME/kanban-mcp/kanban.db`	SQLite数据库文件路径
`KANBAN_DB_NAME`	`kanban`	MySQL数据库名称
`KANBAN_DB_USER`	`kanban`	数据库用户
`KANBAN_DB_PASSWORD`	（自动生成）	数据库密码
`KANBAN_DB_HOST`	`localhost`	数据库主机
`KANBAN_DB_PORT`	`3306`	数据库端口
`MYSQL_ROOT_USER`	`root`	数据库管理员用户
`MYSQL_ROOT_PASSWORD`	（none--尝试套接字身份验证）	数据库管理员密码(必需的除非以操作系统root身份运行）

手册

如果数据库根身份验证有问题（例如套接字身份验证问题、访问受限），手动设置是一个很好的选择。

-- 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;

注：在MariaDB上， 'kanban'@'%' 与localhost套接字连接不匹配——您需要两者 @'localhost' 和 @'%' 用户。

按以下顺序运行迁移文件：

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.sql

配置

凭证

kanban-setup 将数据库凭据写入 .env 用户配置目录中的文件：

Linux/macOS： ~/.config/kanban-mcp/.env （或 $XDG_CONFIG_HOME/kanban-mcp/.env)
窗户： %APPDATA%\kanban-mcp\.env

所有安装方法（pipx、pip、source）都使用相同的位置。您还可以通过环境变量或MCP客户端的设置凭据 env 块。

优先（从高到低）：MCP客户端 env 块→ shell环境变量→ .env 文件。在实践中，只需使用一种方法—— .env 文件来自 kanban-setup 最简单的。

警告： 如果您以前使用MySQL并切换到SQLite，请删除或重命名旧的 .env 文件在 ~/.config/kanban-mcp/.env.剩菜 KANBAN_DB_USER/KANBAN_DB_PASSWORD/KANBAN_DB_NAME 值将无声地触发MySQL自动检测。或者，设置 KANBAN_BACKEND=sqlite 明确地覆盖。

变量	必填	默认	描述
`KANBAN_BACKEND`	没有	（自动检测）	强制后端： `sqlite` 或 `mysql`自动检测在以下情况下使用MySQL `KANBAN_DB_USER`, `KANBAN_DB_PASSWORD`，以及 `KANBAN_DB_NAME` 都已设置，否则为SQLite
`KANBAN_SQLITE_PATH`	没有	`$XDG_DATA_HOME/kanban-mcp/kanban.db`	SQLite数据库文件路径
`KANBAN_DB_HOST`	没有	`localhost`	MySQL数据库服务器主机
`KANBAN_DB_PORT`	没有	`3306`	MySQL数据库服务器端口
`KANBAN_DB_USER`	是（仅MySQL）	--	MySQL数据库用户名
`KANBAN_DB_PASSWORD`	是（仅MySQL）	--	MySQL数据库密码
`KANBAN_DB_NAME`	是（仅MySQL）	--	MySQL数据库名称
`KANBAN_DB_POOL_SIZE`	没有	`5`	MySQL连接池大小
`KANBAN_PROJECT_DIR`	否	--	覆盖项目目录检测
`KANBAN_WEB_PORT`	没有	`5000`	Web UI端口(`kanban-web`)
`KANBAN_WEB_HOST`	没有	`127.0.0.1`	Web UI绑定地址(`kanban-web`)

MCP客户端设置

这 kanban-mcp 服务器通过stdin/stdout（标准MCP STDIO传输）传输JSON-RPC 2.0。任何MCP客户端都可以使用它。如果 kanban-setup 已经写了你的 .env 文件，您只需要命令--no env 需要块。

如果需要显式传递凭据（例如，客户端不继承您的shell环境），请添加 env 块：

"env": {
  "KANBAN_DB_HOST": "localhost",
  "KANBAN_DB_USER": "kanban",
  "KANBAN_DB_PASSWORD": "your_password_here",
  "KANBAN_DB_NAME": "kanban"
}

克劳德代码

添加 ~/.claude.json （全球）或 .mcp.json （每个项目）：

{
  "mcpServers": {
    "kanban": {
      "command": "kanban-mcp"
    }
  }
}

克劳德桌面版

添加 ~/.config/Claude/claude_desktop_config.json （Linux）或 ~/Library/Application Support/Claude/claude_desktop_config.json （macOS）：

{
  "mcpServers": {
    "kanban": {
      "command": "kanban-mcp"
    }
  }
}

双子星命令行工具

添加 ~/.gemini/settings.json:

{
  "mcpServers": {
    "kanban": {
      "command": "kanban-mcp"
    }
  }
}

VS代码/副本

添加 .vscode/mcp.json （每个项目）：

{
  "servers": {
    "kanban": {
      "command": "kanban-mcp"
    }
  }
}

注： VS Code使用密钥 servers，不 mcpServers.

Codex 命令行界面

添加 ~/.codex/config.toml:

[mcp_servers.kanban]
command = "kanban-mcp"

光标

添加 .cursor/mcp.json （每个项目）：

{
  "mcpServers": {
    "kanban": {
      "command": "kanban-mcp"
    }
  }
}

其他MCP客户端

对于任何其他MCP兼容工具：将其指向 kanban-mcp 使用STDIO传输的命令。使用默认的SQLite后端，不需要进行环境配置。如果使用MySQL，工具无法读取 .env 文件（例如，它不继承您的shell环境），传递 KANBAN_DB_* 通过客户端的环境变量配置。

钩子

钩子是使代理自动使用板的原因。没有它们，代理只在您明确要求时与看板mcp交互。

两个钩子作为控制台脚本附带，安装在旁边 kanban-mcp:

kanban-hook-session-start --在会话开始时运行。从钩子的stdin JSON读取项目目录(cwd 字段），在数据库中查找项目，并打印任何正在进行的项目。该输出被注入到对话上下文中，因此代理在没有被告知的情况下知道什么是活动的。

kanban-hook-stop --在会话结束时运行。列出仍在进行中的项目，并建议创建日记条目、更新状态或添加进度注释。这促使代理人（和你）保持董事会的最新状态。

如果项目未被跟踪或数据库无法访问，这两个钩子都会静默退出——它们永远不会阻塞会话。

哪些客户端支持钩子？

客户端	会话挂钩？	配置位置
克劳德代码	是	`~/.claude/settings.json`
Gemini CLI	是	`~/.gemini/settings.json`
VS代码副本	是（预览）	`~/.claude/settings.json`¹或 `.github/hooks/*.json`
Copilot CLI	是	挂钩配置文件
游标	是（插件原语）	钩子配置

¹VS Code Copilot读取Claude Code的钩子配置——如果你已经为Claude Code配置了钩子，VS Code Copiot也会使用它们。

Claude Code、Gemini CLI和VS Code Copilot都使用相同的挂钩格式。Gemini CLI也已设置 CLAUDE_PROJECT_DIR 作为一个兼容性别名，看板挂钩可以在所有三个地方工作，无需修改。

配置

钩子穿过 /bin/sh （Linux/macOS）或 cmd （Windows），哪些可以不读取shell配置文件——必须使用绝对路径。

找到你的路：

# 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.exe

合并到客户端的设置文件中(~/.claude/settings.json 对于Claude Code和VS Code Copilot， ~/.gemini/settings.json 对于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" }] }
    ]
  }
}

窗户：

{
  "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" }] }
    ]
  }
}

如果您已经配置了挂钩，请将看板条目添加到现有数组中——不要替换它们。

提示： install.sh 和 install.ps1 安装完成后，打印一个带有解析路径的即用配置代码段。

用法

第一次会议

安装和配置后，在项目目录中打开您的AI代理。你第一次这样做：

会话开始钩子触发但静默退出（它还不知道这个项目）
代理人需要打电话 set_current_project 使用您的工作目录 绝对路径 --这将自动在数据库中创建项目
从这一点来看，所有的看板工具都与这个项目背道而驰
在会话结束时，停止钩子会列出任何正在进行的项目，并建议记录进度

在同一目录中的后续会话中，start钩子会自动将您的活动项注入对话中——代理会从您停止的地方继续。

没有“创建项目”命令。项目是第一次隐式创建的 set_current_project 需要一个目录。如果代理没有自己调用它，请让它调用——否则一旦项目存在于数据库中，钩子就会处理项目上下文。

注：路径被解析（符号链接， ., ..)在哈希之前，所以 --project . 和 --project $PWD 参考同一个项目。同样适用于 set_current_project.

三个接口

看板mcp提供了三种与相同数据交互的方法：

MCP工具 --AI代理在对话中调用40多种工具。这是主要界面。代理创建项目、跟踪依赖关系、推进状态并记录进度，作为正常工作流程的一部分。你不需要告诉它——会话钩子提供上下文，代理自然地使用这些工具。

Web用户界面 --基于浏览器的人类看板。

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 var

kanban-web 在前台运行。要持久运行它，请使用流程管理器（例如。 systemd, screen, tmux)或者包括web UI的Docker组合堆栈。

macOS注意事项： 端口5000由现代macOS上的AirPlay接收器使用。如果 kanban-web 无法绑定、使用 --port 5001 或设置 KANBAN_WEB_PORT=5001.

该板显示所有状态列（积压→ todo → 正在进行中→ 审查→ done → 关闭），并在它们之间拖放。使用标题中的项目下拉菜单在项目之间切换。卡片显示优先级、标签、史诗成员资格、阻止关系和史诗进度条。

命令行界面 — kanban-cli 用于终端查询、脚本和导出。每个命令都需要 --project PATH （与代理使用的目录路径相同）和可选 --format {text,json}.

CLI参考

所有命令采取 --project PATH 随着 绝对路径 到您的项目目录，以及一个可选 --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-embeddings

提示： 路径被解析（符号链接， ., ..)在哈希之前，所以 --project . 和 --project $PWD 参考同一个项目。

升级

数据库迁移在启动时自动运行，升级后不需要手动迁移步骤。

pipx：

pipx upgrade kanban-mcp

pip：

pip install --user --upgrade kanban-mcp

来源：

cd kanban-mcp && git pull && pip install -e .[dev]

Docker：

./install.sh --upgrade
# Windows: .\install.ps1 -Upgrade

这将重新下载最新的Docker文件，从PyPI重建web映像，并重新启动容器。迁移在容器启动时自动运行。

适用于AI编码代理

克劳德、双子座、GPT、Codex和其他代理商：从这里开始。

如果你的员工要求你安装看板mcp，请严格遵循以下步骤。不要即兴发挥。这 --auto 标志处理所有提示。

1.安装并设置数据库

默认路径使用SQLite——零配置，不需要数据库服务器：

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

如果您的用户特别需要MySQL/MariaDB，请添加 --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 HOST

对于Windows（PowerShell-下载到文件中是因为 irm | iex 不支持传递以下标志 -Auto):

irm https://raw.githubusercontent.com/multidimensionalcats/kanban-mcp/main/install.ps1 -OutFile install.ps1
.\install.ps1 -Auto

这将安装pipx（如果需要），安装看板mcp，创建数据库，运行迁移，并将配置写入 ~/.config/kanban-mcp/.env.

2.添加MCP配置

为您使用的任何工具编写配置条目：

工具	配置文件	密钥	格式
克劳德代码	`.mcp.json` （项目）或 `~/.claude.json` （全球）	`mcpServers`	JSON
克劳德桌面	`~/.config/Claude/claude_desktop_config.json`	`mcpServers`	JSON
Gemini CLI	`~/.gemini/settings.json`	`mcpServers`	JSON
VS代码/副本	`.vscode/mcp.json`	`servers`	JSON
光标	`.cursor/mcp.json`	`mcpServers`	JSON
Codex CLI	`~/.codex/config.toml`	`[mcp_servers.kanban]`	汤姆

服务器条目（JSON示例）：

{
  "kanban": {
    "command": "kanban-mcp"
  }
}

不 env 需要块--从中读取凭据 ~/.config/kanban-mcp/.env 这是安装脚本在步骤1中创建的。

3.验证

kanban-cli --project /path/to/humans/project summary

4.配置挂钩（推荐）

钩子是让你自动使用电路板的东西。如果没有它们，你只能在人类要求时与看板mcp进行交互。

kanban-hook-session-start --在会话开始时运行。读取项目目录，查询正在进行的项目，并将其注入到对话中，以便您知道什么是活动的。
kanban-hook-stop --在会话结束时运行。列出仍在进行中的项目，并提醒您更新状态或创建日记条目。

如果您的客户端支持钩子（Claude Code、Gemini CLI、VS Code Copilot、Copilot CLI、Cursor）：通过解析绝对路径 which，读取客户的钩子配置文件，合并看板钩子条目（保留任何现有的钩子），然后写回。不要覆盖其他钩子条目。看钩子以上部分介绍了每个客户端的配置格式和路径。

入口点

命令	描述
`kanban-mcp`	MCP服务器（STDIO JSON-RPC）——供AI客户端使用
`kanban-web`	本地主机上的Web UI：5000(`--port`, `--host`, `--debug` 旗帜；环境： `KANBAN_WEB_PORT`, `KANBAN_WEB_HOST`)
`kanban-cli`	用于手动查询和钩子脚本的CLI(`--project`, `--format` 旗帜）
`kanban-setup`	数据库设置向导（见下面的标志）
`kanban-hook-session-start`	会话启动钩子——将活动项注入代理会话
`kanban-hook-stop`	会话停止挂钩--提示进度更新

`kanban-setup` 旗帜

标志	描述
`--auto`	非交互模式（跳过所有提示，使用默认值）
`--backend {sqlite,mysql}`	选择后端（默认： `sqlite`)
`--sqlite-path PATH`	自定义SQLite数据库文件路径
`--db-name NAME`	MySQL数据库名称（默认值： `kanban`)
`--db-user USER`	MySQL数据库用户（默认值： `kanban`)
`--db-password PASS`	MySQL数据库密码（默认：自动生成）
`--db-host HOST`	MySQL数据库主机（默认： `localhost`)
`--db-port PORT`	MySQL数据库端口（默认值： `3306`)
`--mysql-root-password PASS`	用于创建数据库的MySQL根密码
`--with-semantic`	安装语义搜索Python包
`--docker`	通过Docker启动MySQL

MCP工具参考

项目管理

工具	说明
`set_current_project`	设置当前项目上下文（在会话开始时以$PWD调用）
`get_current_project`	获取当前项目上下文
`project_summary`	按类型和状态获取项目摘要
`get_active_items`	获取处于“in_progress”状态的项目
`get_todos`	获取处于“积压”状态的项目

项目CRUD

工具	说明
`new_item`	创建新问题、待办事项、专题、史诗、问题或日记条目
`list_items`	列出具有可选类型/状态/标签过滤器的项目
`get_item`	获取特定项目的完整详细信息
`edit_item`	编辑项目的标题、描述、优先级、复杂性和/或父项
`delete_item`	永久删除项目

状态工作流

工具	说明
`advance_status`	将项目移动到其工作流中的下一个状态
`revert_status`	将项目移动到以前的状态
`set_status`	将项目设置为特定状态
`close_item`	将项目标记为已完成/已关闭
`get_status_history`	获取项目的状态更改历史记录
`get_item_metrics`	获取计算指标：交付周期时间、周期时间、进度状态

进度更新

工具	说明
`add_update`	添加进度更新，可选择链接到项目
`get_latest_update`	获取最新更新
`get_updates`	获取最新更新

关系和层次结构

工具	说明
`add_relationship`	添加关系（块、depends_on、relates_to、重复项）
`remove_relationship`	删除关系
`get_item_relationships`	获取项目的所有关系
`get_blocking_items`	获取阻止给定项目的项目
`set_parent`	设置或删除父关系
`list_children`	获取项目的子项（可选递归）
`get_epic_progress`	获取史诗的进度统计数据

文件链接和决策

工具	说明
`link_file`	将文件（或文件区域）链接到项目
`unlink_file`	删除文件链接
`get_item_files`	获取链接到项目的所有文件
`add_decision`	向项目添加决策记录
`get_item_decisions`	获取某个项目的所有决策
`delete_decision`	删除决策记录

搜索和导出

工具	说明
`search`	在项目和更新之间进行全文搜索
`semantic_search`	按语义相似性搜索（需要 `[semantic]` 额外）
`find_similar`	查找与给定项目、决策或更新类似的项目
`rebuild_embeddings`	重建项目的所有嵌入
`export_project`	以JSON、YAML或Markdown格式导出项目数据

时间线

工具	说明
`get_item_timeline`	特定项目的活动时间线
`get_project_timeline`	整个项目的活动时间表

项目类型和工作流

类型	工作流
问题	积压→ todo → 正在进行中→ 审查→ done → 关闭
特性	待办事项列表→ todo → 正在进行中→ 审查→ done → 关闭
史诗般的积压→ todo → 正在进行中→ 审查→ done → 关闭
待办事项→ todo → 正在进行中→ 完成了
问题	积压→ 正在进行中→ 完成了
日记	完成（单一状态）

贡献

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 test

更新日志

看更改日志.md 发布说明。使用以下命令检查您安装的版本：

pipx list | grep kanban-mcp
# or
pip show kanban-mcp

许可证

麻省理工学院

工具	说明
`list_tags`	列出所有带有使用次数的标签
`add_tag`	为项目添加标签
`remove_tag`	从项目中删除标签
`get_item_tags`	获取分配给项目的所有标签
`update_tag`	更新标签名称和/或颜色
`delete_tag`	从项目中删除标记