Kaiten

kaiten-mcp

适用于 Kaiten 的 MCP 服务——将 Kaiten 看板和任务集成到 AI 助手（Cursor、Claude Code 及任何 MCP 客户端）。

直接在聊天中管理卡片：创建任务、在列之间移动、更新描述、添加评论和标签，无需从 Web 界面手动复制，也不会在模型上下文中塞入庞大的 API JSON 响应。

为什么需要它

• 通过 Model Context Protocol 将 Kaiten 集成到 Cursor / Claude Code
• 通过 Agent 操作空间、看板、列和卡片
• 节省令牌：默认返回精简内容（仅在请求时返回描述）
• 可在本地部署（stdio），也可供团队使用（Streamable HTTP / Docker / Kubernetes）

功能

• 为 Cursor 和 Claude Code 提供本地 stdio 传输
• 提供远程 Streamable HTTP（POST /mcp），供团队托管
• 每次请求提供 Kaiten 令牌（凭据不会保存到磁盘）
• 精简列表：默认每页 20 条（最多 100 条），不包含附件和「冗余」嵌套字段
• 提供载荷大小基准测试（kaiten-mcp-benchmark），避免响应随时间膨胀
• 将结构化日志写入 stderr（适用于 stdio MCP）

快速开始

要求

• Python 3.12+
• uv
• Kaiten API 令牌（在你的实例中依次打开“个人资料” → “API 密钥”，例如 https://<公司>.kaiten.ru/profile/api-key）

1. 安装和运行

export KAITEN_API_TOKEN='ваш-токен'
export KAITEN_WORKSPACE_SLUG='ваша-компания'   # → https://ваша-компания.kaiten.ru/api/v1

uvx kaiten-mcp --transport stdio

uvx 会从 PyPI 下载软件包、创建隔离环境并启动服务。 无需克隆仓库。

对于 on-prem / 自定义域名，请使用完整 API 根路径代替 slug：

export KAITEN_BASE_URL='https://kaiten.example.com/api/v1'

其他变量请参阅 .env.example。

2. Cursor

项目配置文件已就绪：.cursor/mcp.json。

1. 将令牌和 workspace 导出到 Cursor 会继承的环境中：

export KAITEN_API_TOKEN='ваш-токен'
export KAITEN_WORKSPACE_SLUG='ваша-компания'

2. 更改环境变量后，重启 Cursor。
3. 打开 Output → MCP Logs，确认服务 kaiten 已连接。
4. 向 Agent 提问：「显示空间」或「查找看板 … 上的任务」。

${env:KAITEN_API_TOKEN} 和 ${env:KAITEN_WORKSPACE_SLUG} 由 Cursor 替换。请勿提交真实令牌。

3. Claude Code

项目配置文件： .mcp.json。

export KAITEN_API_TOKEN='ваш-токен'
export KAITEN_WORKSPACE_SLUG='ваша-компания'
claude mcp list

或者手动配置：

claude mcp add --transport stdio kaiten -- uv run kaiten-mcp --transport stdio

向 Agent 提问的示例

• 「显示 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. 如有需要，调用 add_comment / add_tag_to_task

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：

uv run kaiten-mcp --transport streamable-http --host 0.0.0.0 --port 8000

• 健康检查：GET /healthz
• MCP：POST /mcp

Docker：

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 build -t kaiten-mcp . 构建镜像。

每个客户端都要传入自己的令牌：

Authorization: Bearer <kaiten-api-token>

配置示例：

• examples/remote-mcp/cursor.mcp.json
• examples/remote-mcp/claude.mcp.json

Kubernetes 注意事项：

• 可以使用无状态副本（stateless_http=True）
• TLS 在 Ingress 上配置
• 增大 proxy/read timeout，以支持流式传输
• 不要记录 Authorization 标头
• Kaiten 的限额约为 50 req/s，请在各副本之间分配额度

每个请求都使用 Bearer 令牌的模式是 v1 的审慎选择（不使用浏览器 OAuth）。

环境变量

变量	必填	描述
KAITEN_API_TOKEN	是（stdio）	API 令牌；对于 HTTP，还需通过 Authorization: Bearer 传入
KAITEN_WORKSPACE_SLUG	是*	Slug：acme → https://acme.kaiten.ru/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	否	在日志中显示经过脱敏的精简预览
KAITEN_ENABLE_METRICS	否	记录不含机密信息的 payload 大小指标

* 必须设置 KAITEN_WORKSPACE_SLUG 或 KAITEN_BASE_URL。

节省令牌

• 列表页默认大小：20（最大 100）
• 列表中不包含描述、附件和深层嵌套数据
• 变更操作返回 id/url 和已更改的字段
• 明确标示截断情况：truncated、next_offset、has_more
• 工具的 schema 描述简短

检查响应大小限额：

uv run kaiten-mcp-benchmark
uv run kaiten-mcp-benchmark --check

日志记录

日志始终输出到 stderr（兼容 stdio MCP）。

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。

机密信息会经过脱敏；令牌仅以 fingerprint 形式显示，例如 token_fp=len=40:…ab12。

开发

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

实时 smoke 测试（可选，默认不在 CI 中运行）：

KAITEN_API_TOKEN=... KAITEN_WORKSPACE_SLUG=... uv run pytest -m live

发布版本（PyPI、GHCR、Official MCP Registry）的说明见 RELEASING.md。

目录结构

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 metadata
RELEASING.md

安全

• 每个请求的令牌来自 HTTP Bearer 或 KAITEN_API_TOKEN
• 服务不会将令牌写入磁盘
• 建议使用环境变量，而不是将令牌硬编码到 MCP JSON 中
• Kaiten 端的权限由调用者的令牌决定

常见问题

如何将 Kaiten 连接到 Cursor？
使用 uv 安装依赖，设置 KAITEN_API_TOKEN 和 KAITEN_WORKSPACE_SLUG，然后重启 Cursor——配置已位于 .cursor/mcp.json。

在哪里可以获取 Kaiten API 令牌？
在你的实例中：个人资料 → API 密钥（https://<компания>.kaiten.ru/profile/api-key）。此场景不使用 Kaiten 公共 API 的 OAuth。

此服务与其他 kaiten-mcp 有何不同？
侧重于精简响应和节省模型上下文，并提供现成的远程 Streamable HTTP 方案，供团队使用且无需在服务端存储令牌。

可以为整个团队部署吗？
可以：使用 Docker / Kubernetes 和 streamable-http；每位员工都在标头中传入自己的 Bearer 令牌。

支持 on-prem Kaiten 吗？
支持——将 KAITEN_BASE_URL 设置为你的 /api/v1 地址。

许可证

MIT