mcp-server-zuuna

Name: mcp-server-zuuna
Author: kenzotp

ローカル

github.com/kenzotp生産性05 週間前に更新

リポジトリ

mcp-server-zuuna について

mcp-server-zuunaは、v1 APIを通じてコーディングエージェントをZuunaのカンバンボードに接続します。73種類のツールでボード操作、計画、時間記録、Git関連情報を扱い、コード変更はリポジトリ内で行います。

主な機能

01ボードとカード操作の73ツール
02スプリント、リリース、定期カードの管理
03コメント、チェックリスト、添付ファイル
04時間記録とタイマー操作
05GitイベントとCIチェックの記録
06スコープ別のツール制御と破壊的操作の確認

活用シーン

01コーディングエージェントによるカードの確認と更新
02スプリント計画と作業時間の記録
03コミット、プルリクエスト、CI状況のカードへの紐付け

MCP 対応

Zuuna v1 APIの操作を73種類のMCPツールとして公開し、5種類のプロンプトも提供します。APIトークンを使ったローカル実行と、Zuunaのホスト型MCPコネクターに対応します。

設定

ローカルサーバーの設定はどのクライアントでも共通です。コピーしてクライアントの MCP 設定ファイルに貼り付けてください。

mcp.json · 共通設定

{
  "mcpServers": {
    "kenzotp-mcp-server-zuuna": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-server-zuuna"
      ],
      "env": {
        "ZUUNA_API_TOKEN": "<ZUUNA_API_TOKEN>",
        "ZUUNA_BASE_URL": "<ZUUNA_BASE_URL>",
        "ZUUNA_TIMEOUT_MS": "<ZUUNA_TIMEOUT_MS>"
      }
    }
  }
}

起動コマンドnpx -y mcp-server-zuuna

設定が必要な環境変数

ZUUNA_API_TOKENシークレットBearer API token from your Zuuna workspace. Grant only the scopes the agent needs (boards:read + cards:read is enough for a read-only observer).

ZUUNA_BASE_URLZuuna base URL. Defaults to https://app.zuuna.de.

ZUUNA_TIMEOUT_MSPer-request timeout in milliseconds. Defaults to 15000.

ローカルサーバーにはマシン上の実行環境（Node.js 18 以上など）が必要です。設定ファイルの場所はクライアントごとに異なります。

パッケージ

npmmcp-server-zuuna0.3.0stdio

ツール

掲載時のツール一覧 · 2 週間前に更新

このツールにパラメーターはありません。

詳細

mcp-server-zuuna

Zuunaへのエージェントネイティブなボードアクセス — コーディングエージェント（Claude Code、Cursor、Codex）がZuunaのボードを直接読み取り、操作できる Model Context Protocol サーバーです。

エージェントがボードを操作し、Gitがその内容を正確に保ちます。

エージェントはこのMCPサーバーを介してボードを読み取り、独自のコーディングツールを使ってリポジトリ内で作業します。PRがマージされると、Zuunaのボード上のルールによってカードが移動します。Zuunaが提供するのはインターフェースと検証可能なボードの正確な状態です。コードを書くのはエージェントであり、Zuunaではありません。

ステータス

動作確認済みでテスト済みです。また、トークンモデル、スコープ、ツールの構成をレビューしたうえで、npmに公開済みです（npx -y mcp-server-zuuna）。開発する場合は、下記のソースから実行してください。

ホスト型の代替手段

同じ73個のツールを、何もインストールせずに利用することもできます。Zuunaはapp.zuuna.de/mcpでホスト型MCPコネクターを提供しています（OAuthサインイン、Developerプラン）。Claude Code、Cursor、CodexでこのURLを直接指定すれば、以下のトークンとnpxの手順は不要です。このパッケージは、CIランナー、エアギャップ環境のエージェント、OAuthサインインではなく通常のベアラートークンを使うワークフローなど、ローカルプロセスが必要な場合に利用できます。2つの方法を並べて比較するには、AIエージェント向けカンバンボードをご覧ください。

ツール

73個のツールを領域ごとに分類しています。すべてのツールは有効なトークンで利用できます。Scopes列には、トークンに追加で必要なスコープを記載しています。破壊的と記された8個のツールは、明示的なconfirm: true引数がないと実行されません。

ID

ツール	メソッド＋パス	スコープ
`zuuna_me`	`GET /api/v1/me`	なし

グループ

ツール	メソッド＋パス	スコープ
`zuuna_list_groups`	`GET /api/v1/groups`	`boards:read`
`zuuna_list_group_members`	`GET /api/v1/groups/{groupId}/members`	`boards:read`
`zuuna_list_epics`	`GET /api/v1/groups/{groupId}/epics`	`boards:read`
`zuuna_create_epic`	`POST /api/v1/groups/{groupId}/epics`	`cards:write`
`zuuna_update_epic`	`PATCH /api/v1/groups/{groupId}/epics/{epicId}`	`cards:write`
`zuuna_list_group_cards`	`GET /api/v1/groups/{groupId}/cards`	`cards:read`

ボード

ツール	メソッド＋パス	スコープ
`zuuna_boards`	`GET /api/v1/boards`	`boards:read`
`zuuna_board`	`GET /api/v1/boards/{id}/columns` + `GET /api/v1/boards/{id}/cards`	`boards:read`、`cards:read`
`zuuna_create_board`	`POST /api/v1/boards`	`boards:write`
`zuuna_list_columns`	`GET /api/v1/boards/{boardId}/columns`	`boards:read`
`zuuna_list_board_fields`	`GET /api/v1/boards/{boardId}/fields`	`boards:read`
`zuuna_create_column`	`POST /api/v1/boards/{boardId}/columns`	`boards:write`
`zuuna_list_automations`	`GET /api/v1/boards/{boardId}/automations`	`boards:read`

カード

ツール	メソッド + パス	スコープ
`zuuna_card`	`GET /api/v1/cards/{idOrKey}`	`cards:read`
`zuuna_list_board_cards`	`GET /api/v1/boards/{boardId}/cards`	`cards:read`
`zuuna_search_cards`	`GET /api/v1/cards`	`cards:read`
`zuuna_create_card`	`POST /api/v1/boards/{boardId}/cards`	`cards:write`
`zuuna_create_cards`	`POST /api/v1/boards/{boardId}/cards` (`{"cards":[...]}`)	`cards:write`
`zuuna_update_card`	`PATCH /api/v1/cards/{idOrKey}`	`cards:write`
`zuuna_move_card`	`PATCH /api/v1/cards/{idOrKey}`	`cards:write`
`zuuna_move_card_to_board`	`POST /api/v1/cards/{cardId}/move`	`cards:write`
`zuuna_archive_card`	`POST /api/v1/cards/{cardId}/archive`	`cards:write`
`zuuna_unarchive_card`	`DELETE /api/v1/cards/{cardId}/archive`	`cards:write`
`zuuna_delete_card` （破壊的）	`DELETE /api/v1/cards/{cardId}`	`cards:write`
`zuuna_restore_card`	`POST /api/v1/cards/{cardId}/restore`	`cards:write`

ツール	メソッド + パス	スコープ
`zuuna_list_comments`	`GET /api/v1/cards/{cardId}/comments`	`comments:read`
`zuuna_comment`	`POST /api/v1/cards/{cardId}/comments`	`comments:write`

チェックリスト

ツール	メソッド + パス	スコープ
`zuuna_list_checklist`	`GET /api/v1/cards/{cardId}/checklist`	`cards:read`
`zuuna_add_checklist_item`	`POST /api/v1/cards/{cardId}/checklist`	`cards:write`
`zuuna_update_checklist_item`	`PATCH /api/v1/cards/{cardId}/checklist/{itemId}`	`cards:write`
`zuuna_delete_checklist_item` （破壊的）	`DELETE /api/v1/cards/{cardId}/checklist/{itemId}`	`cards:write`

リレーション

ツール	メソッド + パス	スコープ
`zuuna_list_relations`	`GET /api/v1/cards/{cardId}/relations`	`cards:read`
`zuuna_add_relation`	`POST /api/v1/cards/{cardId}/relations`	`cards:write`
`zuuna_delete_relation` （破壊的）	`DELETE /api/v1/cards/{cardId}/relations/{linkId}`	`cards:write`

添付ファイル

ZNA-2170 以降、アップロードに対応しています。zuuna_upload_attachment にはローカルファイルのパス、またはファイル名とともに Base64 エンコードされたバイトデータを指定します。一覧取得と個別取得で返されるのはメタデータのみで、バイトデータ自体は返されません。

ツール	メソッド + パス	スコープ
`zuuna_list_attachments`	`GET /api/v1/cards/{cardId}/attachments`	`cards:read`
`zuuna_upload_attachment`	`POST /api/v1/cards/{cardId}/attachments`	`cards:write`
`zuuna_get_attachment`	`GET /api/v1/cards/{cardId}/attachments/{attachmentId}` （メタデータのみ）	`cards:read`
`zuuna_delete_attachment` （破壊的）	`DELETE /api/v1/cards/{cardId}/attachments/{attachmentId}`	`cards:write`

時間記録

ツール	メソッド + パス	スコープ
`zuuna_list_card_time`	`GET /api/v1/cards/{cardId}/time`	`time:read`
`zuuna_log_time`	`POST /api/v1/cards/{cardId}/time`	`time:write`
`zuuna_start_timer`	`POST /api/v1/cards/{cardId}/time`	`time:write`
`zuuna_stop_timer`	`POST /api/v1/cards/{cardId}/time`	`time:write`
`zuuna_list_active_timers`	`GET /api/v1/time/active`	`time:read`
`zuuna_update_time_entry`	`PATCH /api/v1/time/{entryId}`	`time:write`
`zuuna_delete_time_entry` （破壊的）	`DELETE /api/v1/time/{entryId}`	`time:write`
`zuuna_import_time_entries`	`POST /api/v1/time/entries`	`time:write`

スプリント

ツール	メソッド + パス	スコープ
`zuuna_list_sprints`	`GET /api/v1/sprints`	`boards:read`
`zuuna_get_sprint`	`GET /api/v1/sprints/{sprintId}`	`boards:read`
`zuuna_create_sprint`	`POST /api/v1/sprints`	`cards:write`
`zuuna_update_sprint`	`PATCH /api/v1/sprints/{sprintId}`	`cards:write`
`zuuna_add_cards_to_sprint`	`POST /api/v1/sprints/{sprintId}/cards`	`cards:write`
`zuuna_remove_card_from_sprint`	`DELETE /api/v1/sprints/{sprintId}/cards/{cardId}`	`cards:write`

定期カード

ツール	メソッド + パス	スコープ
`zuuna_list_recurring_cards`	`GET /api/v1/boards/{boardId}/recurring`	`boards:read`
`zuuna_create_recurring_card`	`POST /api/v1/boards/{boardId}/recurring`	`cards:write`
`zuuna_update_recurring_card`	`PATCH /api/v1/recurring/{id}`	`cards:write`
`zuuna_delete_recurring_card` （破壊的）	`DELETE /api/v1/recurring/{id}`	`cards:write`

リリース

ツール	メソッド + パス	スコープ
`zuuna_list_releases`	`GET /api/v1/releases`	`boards:read`
`zuuna_get_release`	`GET /api/v1/releases/{releaseId}`	`boards:read`
`zuuna_create_release`	`POST /api/v1/releases`	`releases:write`
`zuuna_update_release`	`PATCH /api/v1/releases/{releaseId}`	`releases:write`
`zuuna_delete_release` （破壊的）	`DELETE /api/v1/releases/{releaseId}`	`releases:write`

デプロイ

監視のみです。ホスト型コネクターにも、「デプロイを開始する」ツールはありません（「正直な対応範囲」を参照）。

ツール	メソッド + パス	スコープ
`zuuna_list_deployments`	`GET /api/v1/deployments`	`boards:read`
`zuuna_report_deployment`	`POST /api/v1/deployments`	`deployments:write`

Webhook

ツール	メソッド + パス	スコープ
`zuuna_list_webhooks`	`GET /api/v1/webhooks`	`webhooks:manage`
`zuuna_create_webhook`	`POST /api/v1/webhooks`	`webhooks:manage`
`zuuna_update_webhook`	`PATCH /api/v1/webhooks/{id}`	`webhooks:manage`
`zuuna_delete_webhook` （破壊的）	`DELETE /api/v1/webhooks/{id}`	`webhooks:manage`
`zuuna_test_webhook`	`POST /api/v1/webhooks/{id}/test`	`webhooks:manage`
`zuuna_list_webhook_deliveries`	`GET /api/v1/webhooks/{id}/deliveries`	`webhooks:manage`

ボード上の Git

コミット、ブランチ、PR、CI ステータスをカードにリンクします。これらのいずれも、それ自体でカードを移動することはありません（「正直な対応範囲」を参照）。

ツール	メソッド + パス	スコープ
`zuuna_link_git_branches`	`POST /api/v1/git/branches`	`git:write`
`zuuna_report_ci_checks`	`POST /api/v1/git/checks`	`git:write`
`zuuna_record_git_events`	`POST /api/v1/git/events`	`git:write`

動作に関する注意事項：

エラーは、API 独自のメッセージを含む MCP ツールエラーとして返されます（v1 エンベロープの message に、ステータスと機械可読な code が付加されます）。たとえば、HARD WIP 制限により移動が拒否されると、409 wip_limit_reached が返されます。
リクエストは 1 回のみで、再試行はありません。4xx の応答が再送されることはありません。リクエストは 15 秒後にタイムアウトし（設定可能）、ネットワークエラーとして通知されます。
ZNA-2001 のようなカード表示キーは、カードを指定するあらゆる場所で使用できます。v1 API はキーを識別子として受け付けます。
zuuna_board はカード一覧をページ分割します（1 ページあたり 200 枚。v1 API 独自の上限です）。そのため、大きなボードによってエージェントのコンテキストがあふれることはありません。ページにボード全体が含まれない場合、応答には cardsTruncated: true が設定され、nextCursor が含まれます。次のページを取得するには、これを cardsCursor として送り返します。
zuuna_create_card では、クライアントが任意に選んだ idempotencyKey を指定できます。応答の消失後、または 5xx エラー後に同じキーで再送すると、カードが重複して作成される代わりに、元のカード（200）が返されます。
zuuna_me は hiddenTools リストも返します。トークンのスコープによって非表示になるすべてのツールと、それぞれのツールを使用可能にするスコープを含みます（起動時のスコープゲーティングで適用される境界と同じです）。
起動時にサーバーは自身のトークンのスコープを読み取り（GET /api/v1/me）、それらのスコープで使用できるツールだけを登録します。これはホスト型コネクターで適用されるスコープゲーティングと同じです。この読み取りに失敗した場合（まだネットワークに接続できない、またはトークンが無効など）、代わりにすべてのツールを登録し、その旨を示す 1 行を stderr に出力します。登録されたツールにかかわらず、すべての呼び出しは API によって引き続き強制されます。
ツールに加えて 5 つのプロンプト（session_start、session_end、triage_board、 standup_summary、plan_sprint）が同梱されています。MCP プロンプトを表示するクライアントでの出発点として用意されており、ツールを直接使用するために必須ではありません。

セットアップ

Zuuna ワークスペースの API トークンが必要です。エージェントに許可する操作に応じてスコープを設定してください。読み取り専用の監視であれば、boards:read と cards:read だけで十分です。

サーバーは、クライアントごとに環境変数で設定します。

変数	デフォルト	意味
`ZUUNA_API_TOKEN`	—（必須）	Bearer API トークン
`ZUUNA_BASE_URL`	`https://app.zuuna.de`	Zuuna のベース URL。絶対 http(s) URL である必要があります（無効な値の場合、起動時に失敗します）。http の値を指定すると、トークンが平文で送信されることを示す警告が stderr に表示されます
`ZUUNA_TIMEOUT_MS`	`15000`	リクエストごとのタイムアウト

Claude Code

claude mcp add zuuna \
  -e ZUUNA_API_TOKEN=zk_live_your_token \
  -- npx -y mcp-server-zuuna

または、プロジェクトの .mcp.json に記述します。

{
  "mcpServers": {
    "zuuna": {
      "command": "npx",
      "args": ["-y", "mcp-server-zuuna"],
      "env": { "ZUUNA_API_TOKEN": "zk_live_your_token" }
    }
  }
}

Cursor

~/.cursor/mcp.json（またはプロジェクトの .cursor/mcp.json）に記述します。

{
  "mcpServers": {
    "zuuna": {
      "command": "npx",
      "args": ["-y", "mcp-server-zuuna"],
      "env": { "ZUUNA_API_TOKEN": "zk_live_your_token" }
    }
  }
}

Codex

~/.codex/config.toml に記述します。

[mcp_servers.zuuna]
command = "npx"
args = ["-y", "mcp-server-zuuna"]
env = { "ZUUNA_API_TOKEN" = "zk_live_your_token" }

ソースから実行

git clone https://github.com/kenzotp/mcp-server-zuuna
cd mcp-server-zuuna && npm install && npm run build

次に、npx の代わりにビルド済みバイナリをクライアントに指定します。

claude mcp add zuuna -e ZUUNA_API_TOKEN=zk_live_your_token -- node /path/to/mcp-server-zuuna/dist/index.js

一連の流れ

zuuna_board — エージェントがボードを確認してカードを選びます（または「ZNA-2001 をやって」と指示します）。
エージェントは独自のツールを使ってリポジトリ内でコーディングし、コミットでカードキーを参照します。
PR がマージされると、Git の記録に基づいてカードが移動します。Zuuna の Git 統合機能（webhook／CLI）がコミットと PR をカードに紐付け、ボードのルール（たとえば「PR をマージ → Done に移動」）がカードを移動します。紐付けは最初から機能します。移動のために必要なのは、ボードの「自動化」でルールを一度追加することだけです。その後、エージェントが手動でボードを操作する必要はなくなり、ボードがリポジトリの状態と食い違うこともありません。

ガイド

AI エージェント向けカンバンボード：エージェントがボードをセットアップし、カードの作成や移動、コメント、作業時間の記録を行います。その後はボードのルールがカードを進めます。
セッション間の Claude Code プロジェクト管理：アプリの計画をボード上に保つ CLAUDE.md のルーチンです。次のセッションは、前のセッションが終了したところから始められます。
AI エージェント向け Zuuna：カードから PR のマージまでの流れを英語とドイツ語で紹介します。

対応範囲について

デプロイをトリガーするツールは、まだありません。zuuna_report_deployment（deployments:write）は、パイプラインがすでに実行した処理（ビルド中、成功、失敗）を記録するだけです。実際のデプロイはエージェントではなく、独自の CI が行います。

現在、git:write ツールは 3 つありますが、それぞれの機能は名前から想像されるより限定的です。

zuuna_record_git_events と zuuna_report_ci_checks は、スマートコミット参照または説明で指定されたカードに、コミット／ブランチ／PR の履歴と CI のステータスを紐付けます。
zuuna_link_git_branches は、1 回の呼び出しでリポジトリの進行中ブランチのスナップショット全体を置き換えます。

この 3 つのツールは、どれもカードを移動しません。カードが移動するのは、ボードのルールが適用された場合（上記の「一連の流れ」を参照）、または zuuna_move_card／zuuna_update_card が直接呼び出された場合だけです。自動化もここでは読み取り専用です（zuuna_list_automations）。ツールで自動化を作成、編集、無効化することはできません。添付ファイルはマルチパート形式でアップロードされ（ZNA-2170）、REST ルート独自の制限とエラーが適用されます。ファイルのバイト列を読み取るツールはありません。

開発

npm install
npm run lint     # eslint
npm run build    # tsc -> dist/
npm test         # vitest, fully mocked (no network)

任意のライブスモークテスト。読み取り専用に限定されています（GET /me と GET /boards のみ。作成、移動、コメントは一切行いません）。

ZUUNA_E2E=1 ZUUNA_API_TOKEN=zk_live_your_token npm run test:e2e

Node.js >= 20 が必要です。

ライセンス

MIT

Markdown 対応

ログインしてコメント

基本情報

作者: kenzotp
言語: node
バージョン: 0.3.0
トランスポート: stdio
掲載日: 2026年9月26日
最終更新: 5 週間前
公式 Registry: io.github.kenzotp/mcp-server-zuuna

問題を報告

MCP は初めてですか？

プロトコルの概要から最初のサーバーの導入まで、よくある疑問にまとめて答えます。

入門ガイドを読む

AI アプリケーションが外部のツールやデータソースに統一的な方法で接続するためのオープンなプロトコルです。クライアントはモデルとの対話を担い、MCP サーバーはツール・リソース・プロンプトテンプレートを提供します。標準メッセージでやり取りするため、1 つのサーバーを複数のクライアントで再利用できます。

mcp-server-zuuna

mcp-server-zuuna について

主な機能

活用シーン

MCP 対応

設定

ツール

詳細

mcp-server-zuuna

ステータス

ホスト型の代替手段

ツール

ID

グループ

ボード

カード

コメント

チェックリスト

リレーション

添付ファイル

時間記録

スプリント

定期カード

リリース

デプロイ

Webhook

ボード上の Git

セットアップ

Claude Code

Cursor

Codex

ソースから実行

一連の流れ

ガイド

対応範囲について

開発

ライセンス

コメント

MCP は初めてですか？

MCP（Model Context Protocol）とは？

MCP サーバーとクライアントの違いは？

ローカルとリモート、どちらを選ぶべき？

Claude や Cursor にサーバーを導入するには？

掲載プロジェクトは審査されていますか？「認証済み」とは？

自分のプロジェクトが掲載されています。どう申請できますか？