内容
# kaiten-mcp
<!-- mcp-name: io.github.evvfebruary/kaiten-mcp -->
**用于 [Kaiten](https://kaiten.cn/) 的 MCP 服务器** - 将 Kaiten 看板和任务与 AI 助手（如 [Cursor](https://cursor.com/) 、 [Claude Code](https://docs.anthropic.com/claude-code) 等）以及任何 MCP 客户端集成。
直接在聊天中管理卡片：创建任务、移动到不同栏目、更新描述、添加评论和标签 - 无需从 Web 界面手动复制，也无需在模型上下文中处理大量 JSON 响应。
## 为什么需要它
- 通过 [Model Context Protocol](https://modelcontextprotocol.io/) 将 **Kaiten 连接到 Cursor / Claude Code**
- 使用代理语音操作空间、看板、栏目和卡片
- 节省令牌：默认情况下，响应更紧凑（仅在需要时提供描述）
- 本地部署（stdio）或团队部署（Streamable HTTP / Docker / Kubernetes）
## 功能
- **stdio** 本地传输，适用于 Cursor 和 Claude Code
- **Streamable HTTP** 远程传输（`POST /mcp`），适用于团队托管
- 每个请求使用 Kaiten 令牌（凭证不会保存在磁盘上）
- 紧凑的列表：默认每页 20 条（最多 100 条），不包含附件和冗余字段
- 负载基准测试（`kaiten-mcp-benchmark`），确保响应不会随着时间增长
- stderr 中的结构化日志（适用于 stdio MCP）
## 快速入门
### 要求
- Python 3.12+
- [uv](https://docs.astral.sh/uv/)
- Kaiten API 令牌（在您的实例中，从“个人资料”→“API 密钥”获取，例如 `https://<公司>.kaiten.cn/profile/api-key`）
### 1. 安装和启动
```bash
export KAITEN_API_TOKEN='您的令牌'
export KAITEN_WORKSPACE_SLUG='您的公司' # → https://您的公司.kaiten.cn/api/v1
uvx kaiten-mcp --transport stdio
```
`uvx` 会从 PyPI 下载包，创建隔离环境并启动服务器。
无需克隆存储库。
对于本地部署或自定义域名，请在 `.env.example` 中设置完整的 API 根路径：
```bash
export KAITEN_BASE_URL='https://kaiten.example.com/api/v1'
```
其他变量参见 [.env.example](.env.example)。
### 2. Cursor
项目配置已在 [.cursor/mcp.json](.cursor/mcp.json) 中。
1. 在 Cursor 环境中导出令牌和工作区：
```bash
export KAITEN_API_TOKEN='您的令牌'
export KAITEN_WORKSPACE_SLUG='您的公司'
```
2. 在更改环境变量后重启 Cursor。
3. 打开 **Output → MCP Logs** 并确认 `kaiten` 服务器已连接。
4. 请求代理显示空间或查找指定看板上的任务。
`${env:KAITEN_API_TOKEN}` 和 `${env:KAITEN_WORKSPACE_SLUG}` 由 Cursor 自动替换。不要提交实际的令牌。
### 3. Claude Code
项目配置在 [.mcp.json](.mcp.json) 中。
```bash
export KAITEN_API_TOKEN='您的令牌'
export KAITEN_WORKSPACE_SLUG='您的公司'
claude mcp list
```
或手动：
```bash
claude mcp add --transport stdio kaiten -- uv run kaiten-mcp --transport stdio
```
## 请求代理的示例
- “显示 Kaiten 中的所有空间”
- “查找空间 X 中的看板并创建卡片‘修复登录错误’”
- “将任务 #1234 移至 In Progress 栏目”
- “为任务 #1234 添加评论：准备好审查”
- “为任务 #1234 添加标签‘hotfix’”
工具的典型顺序：
1. `list_spaces` → `list_boards` → `list_columns` / `list_lanes`
2. `create_task` / `list_tasks` / `get_task` / `update_task` / `move_task`
3. 根据需要添加评论或标签
## MCP 工具
| 工具 | 用途 |
| --- | --- |
| `list_spaces` | 空间列表（id，title） |
| `list_boards` | 空间的看板 |
| `list_columns` | 看板的栏目 |
| `list_lanes` | 看板的泳道 |
| `create_task` | 创建卡片（`title` + `board_id`） |
| `get_task` | 任务详情（`include_description` 按需） |
| `list_tasks` | 过滤后的紧凑列表（query，board，column，tag，...） |
| `update_task` | 更新字段（title，description，owner，condition，...） |
| `move_task` | 移动任务（board / column / lane / sort） |
| `add_comment` / `list_comments` | 评论 |
| `list_tags` / `get_task_tags` | 标签 |
| `add_tag_to_task` | 按名称添加标签 |
| `remove_tag_from_task` | 按 ID 删除标签 |
## 远程服务器 / Docker / Kubernetes
Streamable HTTP:
```bash
uv run kaiten-mcp --transport streamable-http --host 0.0.0.0 --port 8000
```
- 健康检查：`GET /healthz`
- MCP：`POST /mcp`
Docker:
```bash
docker pull ghcr.io/evvfebruary/kaiten-mcp:latest
docker run --rm -p 8000:8000 \
-e KAITEN_WORKSPACE_SLUG=您的公司 \
ghcr.io/evvfebruary/kaiten-mcp:latest
```
要构建 Docker 镜像，请运行 `docker build -t kaiten-mcp .`。
每个客户端都传递自己的令牌：
```http
Authorization: Bearer <kaiten-api-token>
```
示例配置：
- [`examples/remote-mcp/cursor.mcp.json`](examples/remote-mcp/cursor.mcp.json)
- [`examples/remote-mcp/claude.mcp.json`](examples/remote-mcp/claude.mcp.json)
Kubernetes 注意事项：
- 无状态副本是允许的（`stateless_http=True`）
- TLS 在 Ingress 上
- 增加流式传输的代理超时
- 不要记录 `Authorization` 头
- Kaiten 的请求限制约为 ~50 req/s - 在副本之间分配预算
该模型使用带有 Bearer 令牌的请求，这是 v1 版本的有意识选择（不是浏览器 OAuth）。
## 环境变量
| 变量 | 必需 | 描述 |
| --- | --- | --- |
| `KAITEN_API_TOKEN` | 是（stdio） | API 令牌；对于 HTTP，还在 `Authorization: Bearer` 中 |
| `KAITEN_WORKSPACE_SLUG` | 是\* | Slug：`acme` → `https://acme.kaiten.cn/api/v1` |
| `KAITEN_BASE_URL` | 是\* | 完整的 API 根路径（on-prem）；优先级高于 slug |
| `KAITEN_HOST` / `KAITEN_PORT` | 否 | HTTP 绑定（默认为 `127.0.0.1:8000`） |
| `KAITEN_LOG_LEVEL` | 否 | `DEBUG` \| `INFO` \| `WARNING` \| `ERROR` |
| `KAITEN_LOG_FORMAT` | 否 | `text` \| `json` |
| `KAITEN_LOG_BODIES` | 否 | 日志中的紧凑预览（redacted） |
| `KAITEN_ENABLE_METRICS` | 否 | 有效载荷大小指标（无密钥） |
\* 需要 **either** `KAITEN_WORKSPACE_SLUG` **or** `KAITEN_BASE_URL`。
## 令牌优化
- 默认列表页大小：**20**（最大 **100**）
- 列表中没有描述、附件和冗余字段
- 变更返回 ID/URL 和已更改字段
- 明确截断：`truncated`、`next_offset`、`has_more`
- 工具模式描述简洁
响应大小基准测试：
```bash
uv run kaiten-mcp-benchmark
uv run kaiten-mcp-benchmark --check
```
## 日志记录
日志始终输出到 **stderr**（与 stdio MCP 兼容）。
```bash
export KAITEN_LOG_LEVEL=INFO
export KAITEN_LOG_FORMAT=json
uv run kaiten-mcp --transport stdio --log-format json
```
有用的事件：`server_starting`、`tool_start` / `tool_success` / `tool_error`、`kaiten_request`、`kaiten_rate_limited`。
机密编辑；令牌仅显示为 `token_fp=len=40:...ab12` 类型的指纹。
## 开发
```bash
uv sync --all-groups
uv run ruff format .
uv run ruff check .
uv run ty check
uv run pytest
uv run kaiten-mcp-benchmark --check
```
实时冒烟测试（可选，默认情况下不在 CI 中）：
```bash
KAITEN_API_TOKEN=... KAITEN_WORKSPACE_SLUG=... uv run pytest -m live
```
发布版本（PyPI、GHCR、Official MCP Registry）的说明见 [RELEASING.md](RELEASING.md)。
## 结构
```text
src/kaiten_mcp/
api/ # HTTP 客户端和端点适配器
tools/ # MCP 工具
auth.py # 请求令牌
config.py # 配置
presentation.py
metrics.py
server.py
__main__.py
tests/
benchmarks/
examples/remote-mcp/
server.json # Official MCP Registry 元数据
RELEASING.md
```
## 安全
- 每个请求使用从 HTTP Bearer 或 `KAITEN_API_TOKEN` 获取的令牌
- 服务器不会将令牌写入磁盘
- 优先使用环境变量而不是 MCP JSON 中的硬编码
- 调用者的 Kaiten 权限由令牌决定
## 常见问题
**如何将 Kaiten 连接到 Cursor？**
通过 `uv` 安装依赖，设置 `KAITEN_API_TOKEN` 和 `KAITEN_WORKSPACE_SLUG`，重启 Cursor - 配置文件已在 [.cursor/mcp.json](.cursor/mcp.json) 中。
**在哪里可以找到 Kaiten 的 API 令牌？**
在您的实例中：个人资料 → API 密钥（`https://<公司>.kaiten.cn/profile/api-key`）。Kaiten 公共 API 不在此场景中使用 OAuth。
**此服务器与其他 kaiten-mcp 有何不同？**
重点是 **紧凑的响应** 和模型上下文的节省，加上适用于团队的远程 Streamable HTTP，无需在服务器上存储令牌。
**我可以为整个团队部署吗？**
可以：使用 `streamable-http` 的 Docker / Kubernetes；每个员工在标头中传递自己的 Bearer 令牌。
**是否适用于本地部署 Kaiten？**
可以 - 设置 `KAITEN_BASE_URL` 为您的 `/api/v1`。
## 许可证
[MIT](LICENSE)
