Kaiten

kaiten-mcp

Kaiten 用 MCP サーバー — Kaiten のカンバンボードとタスクを AI アシスタント（Cursor、Claude Code、および任意の MCP クライアント）と連携します。

チャットから直接カードを操作できます。タスクの作成、列間の移動、説明の更新、コメントやタグの追加が可能です。ウェブインターフェースから手動でコピーしたり、モデルのコンテキストに大量の JSON API レスポンスを入れたりする必要はありません。

これが必要な理由

• Model Context Protocol を通じて Kaiten を Cursor / Claude Code に接続できます
• エージェントに、スペース、ボード、列、カードを操作させることができます
• トークンを節約できます。デフォルトではコンパクトなレスポンスを返します（説明はリクエスト時のみ）
• ローカル（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 からパッケージをダウンロードし、分離された環境を作成してサーバーを起動します。 リポジトリをクローンする必要はありません。

オンプレミス環境やカスタムドメインの場合は、スラッグの代わりに API の完全なルートを設定します。

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

その他の変数については .env.example を参照してください。

2. Cursor

プロジェクト設定ファイルは用意されています：.cursor/mcp.json。

1. Cursor が引き継ぐ環境に、トークンとワークスペースをエクスポートします。

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。

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

または、手動で設定します。

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. 必要に応じて 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 で処理します
• ストリーミング用にプロキシ／読み取りタイムアウトを延長してください
• Authorization ヘッダーをログに記録しないでください
• Kaiten の上限は約 50 req/s です。レプリカ間で予算を分配してください

リクエストごとに Bearer トークンを使用する方式は、v1 で意図的に選択したものです（ブラウザー OAuth ではありません）。

環境変数

変数	必須	説明
KAITEN_API_TOKEN	はい（stdio）	API トークン。HTTP の場合は Authorization: Bearer にも指定します
KAITEN_WORKSPACE_SLUG	はい*	スラッグ：acme → https://acme.kaiten.ru/api/v1
KAITEN_BASE_URL	はい*	API のルート URL 全体（オンプレミス）。スラッグより優先されます
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	いいえ	機密情報を含まないペイロードサイズのメトリクス

* KAITEN_WORKSPACE_SLUG または KAITEN_BASE_URL のいずれかが必要です。

トークンの節約

• リストのデフォルトページサイズ：20（最大 100）
• リストには説明、添付ファイル、深い階層の重複データは含まれません
• ミューテーションは id/url と変更されたフィールドを返します
• 切り詰めは明示されます：truncated、next_offset、has_more
• ツールスキーマの説明は簡潔です

レスポンスサイズの上限を確認します：

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。

機密情報は秘匿化されます。トークンは 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

ライブスモークテスト（任意。デフォルトでは 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 側の権限は、呼び出し元のトークンによって決まります

FAQ

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 のリモート接続にも対応しています。

チーム全体向けにデプロイできますか？
はい。streamable-http を使用して Docker / Kubernetes にデプロイでき、各メンバーがヘッダーで自身の Bearer トークンを渡します。

オンプレミスの Kaiten でも動作しますか？
はい。KAITEN_BASE_URL に /api/v1 の URL を設定してください。

ライセンス

MIT