plane-mcp-server

セルフホスト版Plane（Community Edition） のためのMCP（Model Context Protocol）サーバーです。プロジェクト、ワークアイテム、ステート、ラベル、サイクル、モジュール、コメント、アクティビティ履歴、リンク、メンバー、インテークトリアージをカバーする56のツールをClaudeに提供し、ローカルのチャットセッションからPlaneワークスペース内のすべてのプロジェクトにわたってプロジェクトマネージャーとして機能するのに十分な能力を持ちます。

Planeの公開REST API（/api/v1）に基づいて構築されており、developers.plane.so にドキュメントがあります。Community Editionはプロジェクト、ワークアイテム、サイクル、モジュール、インテーク、ステート/ラベルをカバーしています。このサーバーはその範囲に限定しています。Epics、initiatives、teamspaces、customersはPlane Commercial/Cloud限定の機能であり、意図的に含めていません。

セットアップ

1. Plane APIキーを生成する

Planeインスタンスで: プロフィール設定 → 個人アクセストークン → 個人アクセストークンを追加。

2. 依存関係のインストールとビルド

cd plane-mcp-server
npm install
npm run build

3. 環境変数の設定

参考用に .env.example を .env にコピーしてください。ただし、MCPクライアント（Claude Desktop、Claude Code）は .env ファイルではなく、設定で直接環境変数を渡すことに注意してください。

4. MCPクライアントに追加する

Claude Code（claude mcp add または .mcp.json を編集）:

{
  "mcpServers": {
    "plane": {
      "command": "node",
      "args": ["/absolute/path/to/plane-mcp-server/dist/index.js"],
      "env": {
        "PLANE_BASE_URL": "https://plane.mycompany.com",
        "PLANE_API_KEY": "plane_api_xxxxxxxxxxxxxxxxxxxx",
        "PLANE_WORKSPACE_SLUG": "acme"
      }
    }
  }
}

Claude Desktop（claude_desktop_config.json）: 上記と同じ mcpServers ブロック。

設定を編集したらクライアントを再起動します。plane サーバーが接続され、56のツールが利用可能になるはずです。

Related MCP server: plane-selfhost-mcp

できること

• プロジェクト — 一覧/取得/作成/更新/アーカイブ/削除。ワークスペース内のすべてのプロジェクトを一度に追跡できます。

• ワークアイテム（イシュー） — 完全なCRUD、UUIDまたは人間が読める識別子（ENG-123）による検索、フリーテキスト検索、高度な構造化フィルター検索（ステート、優先度、アサイニー、ラベルによる）。

• ステートとラベル — 各プロジェクトのワークフロー列とタグを確認・管理します。

• サイクル（スプリント） — 作成/更新/削除、ワークアイテムの割り当て・解除、ステータスレポート用の進捗カウントの読み取り。

• モジュール — サイクルと同じライフサイクルで、より長期的な機能グループ向け。

• コメントとアクティビティ — ディスカッションスレッドの読み書き、ワークアイテムのフィールド変更の監査トレイルの読み取り。

• リンク — PR/ドキュメント/デザインをワークアイテムに添付。

• メンバー — 人の名前/メールアドレスをUUIDに解決、プロジェクトのスタッフ配置、ロールの変更。

• インテーク — バックログに入る前の受信リクエストのトリアージ（承認/拒否/スヌーズ/重複）。

すべての一覧/取得ツールは response_format: "markdown" | "json" を受け付けます（デフォルトは読みやすさのためのmarkdown、プログラム的なさらなる利用にはjson）。また、ワークスペースを必要とするすべてのツールは、設定した場合は PLANE_WORKSPACE_SLUG をデフォルトにするため、ほとんどの呼び出しは project_id だけで済みます。

実装していないもの

意図的に範囲を絞り、CE限定にしています: ファイル/添付ファイルのアップロード、ページ、見積もり、タイムトラッキング（ワークログ）、カスタムワークアイテムタイプ/プロパティ、および商用限定のepics/initiatives/teamspaces/customers/IDP同期API。これらは src/tools/ の同じパターンに従って後で追加できます。

典型的なマルチプロジェクトPMセッション

1. plane_list_projects — ワークスペース内のすべてを確認。

2. アクティブなプロジェクトで plane_advanced_search_work_items を優先度/ステートフィルターで実行 — 緊急のものを探す。プロジェクトスコープなので、ワークスペース全体をカバーするにはプロジェクトごとに1回呼び出します。

3. アクティブなプロジェクトで plane_list_cycles、次に plane_list_cycle_work_items — 現在のスプリントのステータスを確認。

4. plane_update_work_item — アイテムをステート間で移動、再割り当て、優先度の変更。

5. plane_add_work_item_comment — ステータスノートを残す。

6. plane_list_intake_issues + plane_update_intake_issue — トリアージキューをクリア。

開発

npm run dev     # tsx watch, runs src/index.ts directly
npm run build   # compile to dist/
npm start       # run compiled dist/index.js

MCP Inspector でテスト:

npx @modelcontextprotocol/inspector node dist/index.js

（Inspectorの環境パネルで PLANE_BASE_URL / PLANE_API_KEY / PLANE_WORKSPACE_SLUG を設定してください。）

エンドポイントの安定性に関する注意

このサーバーはPlaneのホスト型APIドキュメント（developers.plane.so）と、ドキュメント化されたセルフホストの動作に基づいて構築されています。セルフホストインスタンスは同じ /api/v1 サーフェスを共有しますが、正確な動作はPlaneのバージョンによって多少異なる場合があります。あまり一般的でないツール（例: plane_advanced_search_work_items のフィルター構文）がインスタンスで400/404を返した場合は、よりシンプルな plane_list_work_items / plane_list_states / plane_list_labels ツールを使用してクライアント側でフィルタリングするか、インスタンスの独自APIドキュメント（公開されている場合）を <your-plane-url>/api/ で確認してください。