内容
# KamKan MCP 服务端
KamKan 看板专用 MCP 服务端，允许 Claude Code、Codex 和 Gemini CLI 直接读取和写入您的看板。
## 前置条件
- Node.js ≥ 18（运行 `node -v` 检查版本）
- 已安装并配置 KamKan（工作区已配置）
## 安装
```bash
npm install -g kamkan-mcp
```
## 配置命令行界面
### Claude Code
标准安装（工作区自动从 `%APPDATA%\KamKan\settings.json` 发现）：
```bash
claude mcp add --scope user kamkan -- kamkan-mcp
```
便携/自定义安装：
```bash
claude mcp add --scope user -e KAMKAN_WORKSPACE="C:\BOARDS" kamkan -- kamkan-mcp
```
验证是否加载成功： 在 Claude Code 中运行 `/mcp` — `kamkan` 应该显示为绿色。
---
### Codex
添加到 `~/.codex/config.toml`：
**标准配置：**
```toml
[mcp_servers.kamkan]
command = "kamkan-mcp"
```
**便携配置：**
```toml
[mcp_servers.kamkan]
command = "kamkan-mcp"
[mcp_servers.kamkan.env]
KAMKAN_WORKSPACE = "C:\\path\\to\\your\\workspace"
```
---
### Gemini CLI
添加到 `~/.gemini/settings.json`（如果文件不存在，请创建）：
**标准配置：**
```json
{
"mcpServers": {
"kamkan": { "command": "kamkan-mcp" }
}
}
```
**便携配置：**
```json
{
"mcpServers": {
"kamkan": {
"command": "kamkan-mcp",
"env": { "KAMKAN_WORKSPACE": "C:\\path\\to\\your\\workspace" }
}
}
}
```
---
## 标准 vs 便携
| 配置类型 | 工作区查找方式 |
|---|---|
| 标准（默认 KamKan 安装） | 自动从 `%APPDATA%\KamKan\settings.json` 发现 — 不需要环境变量 |
| 便携/自定义 `settingsLocation` | 设置 `KAMKAN_WORKSPACE` 为包含 `settings.json` 的文件夹 |
如果设置了 `KAMKAN_WORKSPACE`，它将优先使用。
---
## 可用工具
| 工具 | 功能 |
|---|---|
| `list_boards` | 列出工作区中的所有看板 ID |
| `get_board` | 获取看板的列和任务 |
| `create_board` | 创建新的看板（可选自定义列） |
| `create_task` | 在列中添加任务 |
| `update_task_title` | 重命名任务 |
| `move_task` | 将任务移动到不同列 |
| `complete_task` | 标记任务完成或未完成 |
| `delete_task` | 删除任务 |
| `get_task_detail` | 读取标签、优先级、截止日期、描述、子任务 |
| `set_task_detail` | 更新任务详情（部分更新安全） |
## 使用示例
配置完成后，可以自然地与代理交互：
```
列出我的看板
显示看板 TODO 中的任务
在看板 TODO 的 Ongoing 列中添加 "修复登录 bug" 任务
将看板 TODO 中的任务 42 移动到 Done 列
创建名为 WORK 的看板，包含列 Inbox、Doing、Review、Done
设置任务 7 的优先级为高，截止日期为 2026-06-01
```
## 任务跟踪技能
该仓库包含技能，告诉 AI 自动在 KamKan 看板上规划和跟踪自己的工作 — 将请求分解为任务，在 Todo → Doing → Done 中移动任务。
### 安装技能
**Claude Code** — 复制到用户技能目录：
```bash
# macOS / Linux
cp skills/claude/kamkan.md ~/.claude/skills/kamkan.md
# Windows
copy skills\claude\kamkan.md %USERPROFILE%\.claude\skills\kamkan.md
```
**Codex** — 复制到用户技能目录：
```bash
# macOS / Linux
mkdir -p ~/.codex/skills/kamkan
cp skills/codex/kamkan/SKILL.md ~/.codex/skills/kamkan/SKILL.md
# Windows
mkdir %USERPROFILE%\.codex\skills\kamkan
copy skills\codex\kamkan\SKILL.md %USERPROFILE%\.codex\skills\kamkan\SKILL.md
```
**Gemini CLI** — 复制到用户技能目录：
```bash
# macOS / Linux
mkdir -p ~/.gemini/skills
cp skills/gemini/kamkan.md ~/.gemini/skills/kamkan.md
# Windows
mkdir %USERPROFILE%\.gemini\skills
copy skills\gemini\kamkan.md %USERPROFILE%\.gemini\skills\kamkan.md
```
### 使用技能
**Claude Code** — 在会话开始时调用：
```
/kamkan MY_BOARD
```
或设置默认看板以自动激活：
```bash
claude mcp add --scope user -e KAMKAN_WORKSPACE="..." -e KAMKAN_TASK_BOARD="MY_BOARD" kamkan -- kamkan-mcp
```
**Codex** — 同样：输入 `/kamkan MY_BOARD` 或在 `config.toml` 的环境块中设置 `KAMKAN_TASK_BOARD`。
**Gemini CLI** — 同样：输入 `/kamkan MY_BOARD` 或在 `~/.gemini/settings.json` 的环境块中设置 `KAMKAN_TASK_BOARD`。
激活后，AI 将：
1. 将您的请求分解为离散任务并添加到看板
2. 在开始任务时将其移动到 Doing，在完成任务时移动到 Done
3. 在出现新任务时将其添加到看板
4. 在会话结束时报告摘要
---
## 工作区未找到？
如果服务端无法找到您的工作区，请显式设置环境变量：
```bash
# 在 KamKan → 设置 → 工作区中找到工作区路径
export KAMKAN_WORKSPACE="/path/to/your/workspace"
```
然后将其添加到上面的便携式部分中。
