Planka MCP

planka-mcp

41 個の MCP ツールを使って、Claude Code から Planka 2.x のボードを操作します。 書き込み後に再読み込みして検証するため、成功の報告はボードの状態と一致します。 オプションのワークフローを使うと、ボードをエージェント作業用の永続的なメモリにできます。

スペイン語で読む

You talk to Claude Code
          │
          ▼
  planka-mcp (stdio) ─── HTTPS + JSON ───▶ Planka 2.x
          │                                  │
          └──── reads the result back ◀──────┘

警告

古い @gogogadgetbytes/planka-mcp パッケージは、Planka 2.x では何も行わずに成功を報告することがあります。 既存のインストールを置き換える前に、5 つのサイレント失敗に関する注意点をお読みください。

MCP を初めて使う方へ：まずはこちらをお読みください

MCP は、Claude Code が別のプログラムから提供されるツールを呼び出せるようにする標準規格です。 このリポジトリでは、それらのツール呼び出しを Planka API リクエストに変換する、小さなローカルプログラムを実行します。 このプログラムは Claude 自身ではなく、専用の Planka ユーザーとして動作するため、Planka の認証情報が必要です。 認証情報はお使いのマシンに保存され、プロジェクトレベルの .mcp.json ファイルに書き込まれることはありません。 Claude Code はセッション開始時に MCP サーバーを読み込むため、セットアップや設定を変更した後は再起動してください。

要件

• Node.js 18 以降と npx
• 接続可能な Planka 2.x インスタンス
• 対象のプロジェクトとボードを表示できる専用の Planka ユーザー
• MCP クライアントのいずれか 1 つ：Claude Code、Codex CLI、Cursor、VS Code
• セットアップ時にボードを作成する必要がある場合に限り、プロジェクトマネージャーのロール

Linux と macOS に対応しています。Bun ランタイムは不要です。

インストール

クライアントごとに 1 つのコマンドでインストールできます。どの方法でも npx を使って公開済みパッケージを実行するため、クローンもビルドも不要です。

クライアント	ワンライナー
Claude Code（プラグイン：MCP + スキル + 事前チェック）	/plugin marketplace add omnicoreos/planka-mcp を実行し、その後 /plugin install planka@planka-mcp を実行
Claude Code（サーバーのみ）	claude mcp add --scope user --transport stdio planka --env PLANKA_BASE_URL=https://planka.example.com --env PLANKA_API_KEY=<key> -- npx -y @omnicoreos/planka-mcp
Codex CLI	codex mcp add planka -- npx -y @omnicoreos/planka-mcp（その後、下記の env ブロックを追加）
Cursor
VS Code
いずれのクライアントでも、ガイド付き	npx @omnicoreos/planka-mcp init --client claude|codex|cursor|vscode|print

Cursor と VS Code のリンクにはプレースホルダーキーが含まれており、実際のキーは含まれていません。ディープリンクはブラウザーの履歴に残るためです。どちらのクライアントも認証情報を直接入力するよう求めます。VS Code では promptString 入力を通じて求めるため、コミットされる .vscode/mcp.json にシークレットは含まれません。

planka-mcp init

npx @omnicoreos/planka-mcp init --client claude     # claude mcp add, user scope
npx @omnicoreos/planka-mcp init --client codex      # appends to ~/.codex/config.toml
npx @omnicoreos/planka-mcp init --client cursor     # merges ~/.cursor/mcp.json (0600) + prints the deeplink
npx @omnicoreos/planka-mcp init --client vscode     # writes .vscode/mcp.json with a secret prompt
npx @omnicoreos/planka-mcp init --client print      # prints every snippet, writes nothing

ターミナルに接続して実行すると、必要な情報を尋ねます。--base-url、--api-key、--board、--email、--password を指定すると、対話なしで実行できます。何かを書き込む前に、認証付きの GET /api/users/me を 1 回実行します。これにより、SPA を指すベース URLや、一度も正常に機能していない認証情報を検出できます。--dry-run を指定すると、変更内容を正確に表示し、何も変更しません。

すべての設定出力処理で既存の設定をマージします。既存の planka エントリーがある場合はその旨を報告して変更せず、同じファイル内のほかのサーバー設定も保持します。ホームディレクトリに書き込むファイルのパーミッションは 0600 に設定されます。

./scripts/setup.sh は init --client claude のエイリアスです。ボードの選択または作成も行い、作成・ラベル付け・コメント・削除の一連のスモークテストを実行する、以前からのガイド付きインストーラーも引き続き利用できます。こちらは node scripts/setup.mjs で実行します。

Claude Code プラグイン

このプラグインは、MCP サーバー、2 つのワークフロースキル、そして最初のツール呼び出しより前に認証情報の欠落や http:// のベース URL を検出する SessionStart の事前チェックをインストールします。

/plugin marketplace add omnicoreos/planka-mcp
/plugin install planka@planka-mcp

プラグインを有効にすると、Claude Code はベース URL と API キーを尋ね、キーを settings.json ではなく OS のキーチェーンに保存します。Codex は .codex-plugin/plugin.json と .agents/plugins/marketplace.json を通じて、同じリポジトリを読み込みます。

プラグインには権限ルールを同梱できません。これだけは引き継がれないため、クライアント側の拒否リストではなく、代わりに PLANKA_READ_ONLY と PLANKA_DISABLED_TOOLS（以下を参照）を使ってください。どのランタイムでも機能し、コンテキストも消費しません。

Codex の env ブロック

codex mcp add では認証情報を指定できないため、~/.codex/config.toml に追加してください（または init --client codex に任せてください）。

[mcp_servers.planka]
command = "npx"
args = ["-y", "@omnicoreos/planka-mcp"]
env = { PLANKA_BASE_URL = "https://planka.example.com", PLANKA_API_KEY = "<key>" }

動作確認

まず、Claude Code の設定を確認します。

claude mcp list
claude mcp get planka

次に、Claude Code を完全に再起動してください。MCP サーバーはセッション開始時に読み込まれます。プロジェクトの .mcp.json でサーバーを設定した場合は、そのプロジェクトで Claude Code を開き、プロンプトが表示されたらプロジェクト単位のサーバーを承認してください。プラグインをインストールした場合は、/plugin に表示され、起動に失敗したサーバーは Errors タブに表示されます。

Claude Code に次のように尋ねます。

Show me my Planka projects and boards. In the Pending list, create a card named
"MCP is working" with the description "Created from Claude Code", then read it back.

Claude からツールが見えない場合は、まず再起動し、その後トラブルシューティングに従ってください。

認証

認証方法は 2 つあり、併用できません。両方を設定すると設定エラーになります。Planka は Authorization を優先して読み込み、両方が送信された場合は x-api-key を通知なしで無視するためです。

	PLANKA_API_KEY（推奨）	PLANKA_AGENT_EMAIL + PLANKA_AGENT_PASSWORD
送信方法	すべてのリクエストで X-Api-Key: <prefix>_<secret>	POST /api/access-tokens の後、Authorization: Bearer
ログインの往復	なし	セッションごとに 1 回、25 分ごとに更新
サインインのレート制限	対象外	1 つの ID あたり 60 秒間に 10 回のログイン — 複数のエージェントが同時に起動するとすぐに上限に達します
ディスク上のパスワード	なし	あり。クライアントの設定ファイルに保存されます
添付ファイルのダウンロード	利用可能	利用可能

手順：スコープを限定したエージェントユーザーと API キー

Planka の管理者が実行する 4 つの手順です。結果として作成されるユーザーが閲覧できるのは、指定したボードだけです。これはこのサーバーではなく、Planka 自体によって強制されます。

1. 最も低いグローバルロールでユーザーを作成します。 Planka の UI で、Administration → Users → Add user を選び、ロールを boardUser にします。boardUser はプロジェクトを作成できず、自分自身にメンバーシップを付与することもできません。

2. 作業対象とするボードのみにメンバーシップを付与します。

   curl -X POST "$PLANKA_URL/api/boards/<BOARD_ID>/board-memberships" \
     -H "Authorization: Bearer $ADMIN_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{"userId":"<USER_ID>","role":"editor"}'
   

   読み取りとコメントはできても、カードの作成や移動はできないエージェントには "role":"viewer" を使います。GET /api/projects が返すのは、これらのメンバーシップから導出されたプロジェクトのみです。それ以外のすべてのボードは 404 を返します。

3. API キーを発行します（管理者専用エンドポイント）。キーが表示されるのは included.apiKey での一度だけです。Planka にはそのハッシュとプレフィックスのみが保存されます。

   curl -X POST "$PLANKA_URL/api/users/<USER_ID>/api-key" \
     -H "Authorization: Bearer $ADMIN_TOKEN"
   

4. キーだけを使うようにサーバーを設定します。 PLANKA_AGENT_EMAIL と PLANKA_AGENT_PASSWORD を削除します。

   {
     "mcpServers": {
       "planka": {
         "command": "npx",
         "args": ["-y", "@omnicoreos/planka-mcp"],
         "env": {
           "PLANKA_BASE_URL": "https://planka.example.com",
           "PLANKA_API_KEY": "abcd1234_0123456789abcdef0123456789abcdef"
         }
       }
     }
   }
   

キーのローテーションは、手順 3 を再度行います。新しいキーを発行すると、古いキーは無効になります。

サーバーのスコープ設定

API キーはユーザーの権限を引き継ぎます。API キー自体にスコープはありません。そのため、スコープ設定は 3 つのレイヤーで行われ、それぞれ他のレイヤーではカバーできない部分を担います。

Layer 1 · PLANKA          the only layer an agent cannot talk its way around
  boardUser + board memberships + the API key above
  ⇒ everything outside the allowed boards is 404/403 at the API

Layer 2 · THIS SERVER     ergonomics, and defence against the agent itself
  the environment variables below; they travel with the package,
  so Claude Code, Codex and Cursor all get the same rules

Layer 3 · THE CLIENT      survives a downgrade of this package
  .claude/settings.json deny/ask rules, Codex enabled_tools/disabled_tools

レイヤー 1 には実際の強制力がありますが、「planka_get_board を呼び出さないでください。コンテキストを 40 倍消費します」のような指定はできません。レイヤー 2 ならそのような指定が可能で、すべてのランタイムに適用されます。レイヤー 3 は、このパッケージを古いバージョンに固定しても有効です。

レイヤー 2：環境変数

変数	値	機能
PLANKA_DEFAULT_BOARD_ID	1 つのボード ID	boardId を、これを指定するすべてのツールで省略可能にし、このボードをデフォルトにします。ID を取得するためだけにエージェントが呼び出す planka_get_structure を省けます。
PLANKA_ALLOWED_BOARD_IDS	カンマ区切りのボード ID	リストにないボードは planka_get_structure から除外され、そのボードを指定する呼び出しは、リクエストがプロセス外に送信される前に拒否されます。
PLANKA_ALLOWED_PROJECT_IDS	カンマ区切りのプロジェクト ID	同じ制限を 1 つ上のレベルで適用します。
PLANKA_READ_ONLY	true または 1	書き込みツール 27 個を tools/list から非表示にし、呼び出された場合も拒否します。
PLANKA_HIDE_DEPRECATED	true または 1	非推奨のツール 7 個（manage_labels、manage_lists、manage_comment、add_comment、get_board、list_cards、list_lists）を tools/list から除外し、コンテキストを約 6.8 kB 節約します。これらのツールは引き続き呼び出し可能なので、キャッシュされたツールリストも引き続き使えます。
PLANKA_DISABLED_TOOLS	カンマ区切りのツール名	個々のツールを無効にします。planka_ 接頭辞は省略可能です。get_board と planka_get_board は同じ意味です。
PLANKA_PROTECTED_LIST_IDS	カンマ区切りのリスト ID	これらのリストへのカードの作成または移動、リスト自体の編集または削除、カードをこれらのリストから移動、アーカイブ、または削除する操作を拒否します。
PLANKA_SUMMARY_DECISION_LISTS	カンマ区切りの列名または ID	呼び出しで指定がない場合に、planka_board_summary がカードを返す列です。未設定の場合、カードは返されず、ボードの構造だけが返されます。
PLANKA_SUMMARY_HIGHLIGHT_LABEL	1 つのラベル名	planka_board_summary でカードがブロックされていないことを示すラベルです。未設定の場合、ハイライト表示はありません。
PLANKA_MCP_PREFLIGHT	full	プラグインの SessionStart フックのみが読み取ります。サーバーバイナリも起動し、stdio バナーが表示されるまで待機します。キャッシュがない状態では npx のダウンロードが発生するため、デフォルトでは無効です。
PLANKA_MCP_COMMAND	コマンド	同じフックが読み取ります。npx -y @omnicoreos/planka-mcp の代わりに起動するコマンド（ローカルのチェックアウト、固定されたバイナリなど）を指定します。

**サーバーには、ボードの用語があらかじめ設定されていません。**列名や 「準備完了」を示すラベルは、使う言語に合わせて設定できます。最後の 2 つの変数で、 デプロイ時にボードの構成をサマリーに伝えます。何にも一致しないヒントは、 空の回答としてではなく warnings に返されます。

"PLANKA_SUMMARY_DECISION_LISTS": "decision,probalo,miralo",
"PLANKA_SUMMARY_HIGHLIGHT_LABEL": "decidido"

**許可リストでは名前ではなく、必ず ID を使います。**ボードの編集権限があるユーザーなら誰でもボード名を変更できるため、名前ベースの許可リストは 1 回の編集で回避されます。Planka の ID は変わりません。

これらの設定の役割と限界について、2 点補足します。

• PLANKA_READ_ONLY はツールを非表示にするだけで、アカウントを読み取り専用にはしません。それが本当に必要な場合は、上記の手順 2 で "role":"viewer" と組み合わせてください。
• PLANKA_PROTECTED_LIST_IDS は安全策であり、権限設定ではありません。Planka にはリスト単位の権限がありません。「自分でカードを Merged に移動しないでほしい」という用途には適していますが、セキュリティが重要な用途には適していません。

例 — 1 つのボードを読み取り、コメントを投稿するだけのエージェント：

"env": {
  "PLANKA_BASE_URL": "https://planka.example.com",
  "PLANKA_API_KEY": "abcd1234_0123456789abcdef0123456789abcdef",
  "PLANKA_DEFAULT_BOARD_ID": "1234567890123456789",
  "PLANKA_ALLOWED_BOARD_IDS": "1234567890123456789",
  "PLANKA_DISABLED_TOOLS": "get_board",
  "PLANKA_PROTECTED_LIST_IDS": "9876543210987654321"
}

41 個のツール

ID は文字列です。まず planka_get_structure を使い、その後は Planka が返す ID を使ってください。推測してはいけません。

ツール	機能
planka_get_structure	表示可能なプロジェクト、ボード、リストを一覧表示します
planka_get_board	非推奨です。 1つのボード全体を、最大 limit 枚のカードまで読み込みます
planka_board_summary	1回の呼び出しで概要を取得します。列ごとの件数、ID付きのラベル、さらに必要に応じて指定した列のカードを返します
planka_find_cards	カードを読み込むためのツールです。1つの列（listId）を対象にするか、テキスト、ラベル、メンバーでボードを検索します
planka_list_lists	非推奨です。 cardsFrom: [] を指定した planka_board_summary の別名です
planka_list_cards	非推奨です。 listId を指定した planka_find_cards の別名です
planka_create_card	カードを作成します。タスクやラベルも追加できます
planka_get_card	カードの概要を取得します。必要に応じて detail: "full" と withComments を指定できます
planka_update_card	タイトル、説明、期限、または完了状態を更新します
planka_move_card	カードを別のリストまたは位置に移動します
planka_delete_card	カードを完全に削除します
planka_create_tasks	カードにチェックリストのタスクを追加します
planka_update_task	タスクの名前を変更するか、完了にします
planka_delete_task	タスクを削除します
planka_create_label	ボードのラベルを作成します
planka_update_label	ラベルの名前または色を変更します
planka_delete_label	ボードとすべてのカードからラベルを削除します
planka_manage_labels	非推奨です。 action を上記3つのツールに振り分ける別名です
planka_set_card_labels	ラベルを追加または削除し、最終状態を確認します
planka_create_comment	Planka 2.x 専用エンドポイントを使ってコメントを追加します
planka_get_comments	ページ分割されたコメントを取得します（limit、beforeId、all）
planka_update_comment	既存のコメントを書き換えます
planka_delete_comment	コメントを削除します
planka_add_comment	非推奨です。 planka_create_comment の別名です
planka_manage_comment	非推奨です。 action を更新または削除に振り分ける別名です
planka_create_list	ボードにリスト（列）を作成します
planka_update_list	列の名前、位置、または分類を変更します
planka_delete_list	列 と、列内のすべてのカード を削除します
planka_manage_lists	非推奨です。 action を上記3つのツールに振り分ける別名です
planka_add_attachment	ローカルファイルをカードにアップロードし、正常に添付されたことを確認します
planka_get_attachments	カードの添付ファイルを、種類、サイズ、ダウンロードURLとともに一覧表示します
planka_view_attachment	添付ファイルの内容を返します。画像は表示可能な形式で返されます
planka_delete_attachment	添付ファイルを削除します
planka_card_history	1つのカードのアクティビティログを、作成、移動、担当者の割り当て、タスクの完了などの人が読める形式で返します
planka_board_activity	指定日以降にボード上で移動した項目を、カードごとにまとめて返します
planka_set_card_members	メンバーを割り当てるか解除し、最終的なメンバー構成を確認します
planka_list_users	割り当て可能なユーザーを一覧表示します。ボード単位に絞った代替手段もあります
planka_whoami	このサーバーのアカウント、ボード上の役割、Planka のバージョン、アクセス ポリシーを返します
planka_duplicate_card	タスク、ラベル、メンバーを含めてカードを複製します
planka_archive_card	カードをボードの非表示アーカイブに移動するか、アーカイブから復元します
planka_move_list_cards	1つの列にあるすべてのカードを別の列に移動し、件数を返します
読み取りは、すべて次の原則に従います。デフォルトでは簡潔な要約を返し、詳細はパラメーターで取得します。planka_board_summary は1回の呼び出しでセッションを開始します。listId を指定した planka_find_cards は、GET /api/lists/:id を通じて1回のリクエストで列全体を読み取るため、total は列の実際の件数となり、回答には truncated: false が含まれます。同じツールで listId を指定しない場合は、ボードを検索します。185枚のカードがある参照ボードで計測したところ、非推奨の planka_get_board は56,112文字から17,215文字に、planka_get_structure（withLists: false）は696文字から203文字になり、159枚のカードがある列の読み取りに必要なリクエストは5回から2回に減りました。すべての読み取りで total、returned、hasMore が報告されるため、途中で切り詰められた回答が完全なものに見えることはありません。また、Planka ではアーカイブとゴミ箱がボードの読み取り対象外となるため、ボード由来の読み取りにはすべて excludesArchived: true が含まれます。

すべての入力フィールドと、各ツールの完全なペイロードについては、ツールのリファレンスをご覧ください。

接続時にクライアントが学習すること

initialize ハンドシェイクでは、セッションの開始方法、ID の取得元、カードのすべてのコメントが重要である理由、そして Planka が 403 の意味で 404 を返すことなど、短いサーバー指示が返されます。Claude Code はこれらをセッションのシステムプロンプトに追加し、Codex CLI はツール一覧と併せて読み込むため、全41件のツール説明に繰り返し記載するのではなく、共通のガイダンスを一度だけ示せます。また、すべてのツールで表示タイトルと4つすべての MCP 動作ヒントを明示的に公開し、仕様の悲観的なデフォルト値を引き継がないようにしています。さらに、Claude Code が動作に反映する2つの _meta キーも設定されています。データを削除するツールでは確認プロンプトを必須にし、planka_view_attachment では出力上限を引き上げます。詳しくはサーバー指示と注釈をご覧ください。

リソースとプロンプト

もう2つの機能があります。いずれも要求されるまではコストがかからないため、長文のガイダンスは、すべてのセッションで毎回コストが発生する指示ではなく、ここに配置しています。Claude Code と Cursor はどちらも両方に対応しています。Codex はどちらにも対応していないため、ここにある内容は必須ではありません。

リソースでは、パッケージに同梱されているガイドを提供します。Claude Code では @ で参照し、Cursor ではリソースピッカーから利用します。

URI	内容
planka://workflow/readme	任意のボードワークフロー：列、ラベル、誰が何を移動するか
planka://workflow/board-template	新しいボードに作成する列とラベル
planka://workflow/skills/orchestrator	ディレクターのスキル全文
planka://workflow/skills/close-card	クローズ用スキル全文
planka://gotchas/planka-2x	呼び出しが見当違いの回答を返したときの、Planka 2.x の実際の動作
planka://labels/colors	planka_create_label と planka_update_label が受け付けるすべての色。スキーマから生成

プロンプトは3つの開始方法を提供し、Claude Code では /mcp__planka__<name> として表示されます。

プロンプト	引数	内容
planka-open-session	boardId?、since?	この順序で、概要、最近の動き、重要な列を確認します
planka-close-card	cardId、listId?	スレッド全体を読み、誠実な完了コメントを書き、カードを移動し、verified を確認します
planka-board-triage	boardId?、lists?	人の対応待ちの列を巡回し、各カードを1つの質問にまとめます

任意のエージェントワークフロー

MCP サーバーは単独で動作します。この任意の方法は、エージェントのセッション間で、作業の目的、変更内容、今後も変わらないことを保つという、別の問題を解決します。

段階的に導入してください。

1. MCP ツールだけを使います。
2. ボードの状態、カードテンプレート、人とのハンドシェイクを追加します。
3. カードごとに1つのワークツリーを用意し、ディレクターが作業者を調整します。

セッションをまたいで引き継げるボードから始めてください。ボードテンプレート、コピーして使えるClaude Code スキル、任意のワークツリーヘルパーは、それぞれ独立して利用できます。

トラブルシューティング

• 症状、原因、具体的な修正方法
• Planka 2.x で古い MCP サーバーが警告なしに動作しなくなる理由
• ツールの完全なペイロード

バグを報告する際は、Planka のバージョン、Node のバージョン、ツール名、エラーテキストを含めてください。認証情報やアクセストークンは決して貼り付けないでください。

クレジットとライセンス

これは、ゼロから独自に実装したものではなく、MIT ライセンスのフォークです。 gogogadgetbytes/planka-mcp 上流への謝辞、保守されている修正、および未回答のプルリクエストについては、CREDITS.md をご覧ください。

元の貢献者および現在の貢献者に関する告知については、LICENSE をご覧ください。

開発

npm ci
npm run build
npm test

実際のスモークテストは、書き込み可能なボードを変更し、テスト後に後片付けを行うため、オプトイン方式です。stdio 経由で 41 個すべてのツールを実行し、各書き込みを Planka の生 API と照合します。名前付きチェックは 90 件以上あります。

export PLANKA_BASE_URL="https://planka.example.com"
export PLANKA_AGENT_EMAIL="[email protected]"
export PLANKA_AGENT_PASSWORD="<YOUR_PASSWORD>"
export PLANKA_SMOKE_BOARD_ID="1234567890123456789"
npm run test:smoke

npm run test:smoke は最初にビルドするため、古い dist/ をテストすることはありません。任意の 4 つの変数で設定を調整できます。

変数	説明
PLANKA_SMOKE_LIST_ID	スクラッチカードを作成する列です。指定しない場合は、スクラッチ用と思われる列を選択し、該当する列がなければ最初の列を使用します
PLANKA_SMOKE_FAIL_AFTER	後片付けが引き続き実行されることを確認するため、チェック <n> の後にエラーを発生させます
PLANKA_MCP_ENTRY	サーバーのエントリーポイントです。既定値は dist/index.js です
VERBOSE	1 に設定すると、各チェックのペイロードを出力します

変更を提出する前に CONTRIBUTING.md をご覧ください。リリースの識別情報は project.identity.json に集約されています。独自の名前空間で公開する前に、これを更新して npm run sync:identity を実行してください。