Plane MCP Server

Plane MCP Server

Plane 用の Model Context Protocol サーバーです。 AI エージェントがプロジェクト、作業項目、サイクル、モジュール、リリース、顧客などを読み取り、管理するためのツールを提供します。

FastMCP と公式の plane-sdk を基盤に構築されています。

• 30 個のツール。Plane の各リソースにつき 1 個で、207 個の操作を網羅します
• ローカルまたはリモート — stdio、ストリーム可能な HTTP、SSE
• OAuth または API キーによる認証

クイックスタート

Plane から API キーを取得します：ワークスペース設定 → API トークン。

以下を MCP クライアントの設定に追加します。

{
  "mcpServers": {
    "plane": {
      "command": "uvx",
      "args": ["plane-mcp-server", "stdio"],
      "env": {
        "PLANE_API_KEY": "<your-api-key>",
        "PLANE_WORKSPACE_SLUG": "<your-workspace-slug>"
      }
    }
  }
}

uvx はインストール不要です。Python 3.10 以降が必要です。

セルフホスト版の Plane では、"PLANE_BASE_URL": "https://plane.example.com" を追加します。

トランスポート

stdio — ローカル

MCP クライアントのサブプロセスとして実行します。設定は上記のとおりです。PLANE_API_KEY と PLANE_WORKSPACE_SLUG が必要です。

PLANE_API_KEY=... PLANE_WORKSPACE_SLUG=... uvx plane-mcp-server stdio

OAuth を使った HTTP — ホステッド

https://mcp.plane.so/http/mcp

接続時に OAuth フローが処理されるため、設定に認証情報を含める必要はありません。ネイティブのリモート MCP に対応していないクライアントでは、mcp-remote でブリッジします。

{
  "mcpServers": {
    "plane": {
      "command": "npx",
      "args": ["mcp-remote@latest", "https://mcp.plane.so/http/mcp"]
    }
  }
}

Node.js 22 以降が必要です。

個人用アクセストークンを使った HTTP — ホステッド

https://mcp.plane.so/http/api-key/mcp

ヘッダー	値
Authorization	Bearer <PAT>
X-Workspace-slug	<workspace-slug>

{
  "mcpServers": {
    "plane": {
      "command": "npx",
      "args": ["mcp-remote@latest", "https://mcp.plane.so/http/api-key/mcp"],
      "headers": {
        "Authorization": "Bearer <PAT>",
        "X-Workspace-slug": "<workspace-slug>"
      }
    }
  }
}

SSE — 非推奨

https://mcp.plane.so/sse は下位互換性の維持のみを目的としています。代わりに HTTP トランスポートを使用してください。

ツール

サーバーはリソースごとに 1 個、合計 30 個のツールを公開します。各ツールは、操作を選択する action パラメーターを受け取ります。

workitem(action="create", project_id=..., name="Fix login")
workitem(action="list", project_id=..., pql='state__group = "started"')
cycle(action="archive", project_id=..., cycle_id=...)

各ツールの説明には、必須および任意のパラメーターとともに、そのツールの操作が記載されているため、呼び出し時にカタログを確認できます。

→ ツールと操作の完全なリファレンス

作業項目のクエリ

一覧表示、件数取得、検索では、Plane のクエリ言語である PQL を使用できます。

workitem(action="list", project_id=..., pql='state__group = "started" AND priority = "urgent"')
workitem(action="count", pql='assignees__id = "<member id>"', group_by="state_id")

構文、演算子、実例の完全なリファレンスについては、get_pql_reference を呼び出してください。

操作ごとのツールからのアップグレード

以前のリリースでは、API 操作ごとに 1 個のツールを公開していました。既存の連携は引き続き動作します。177 個の名前のうち 169 個は引き続き統合ツールに解決されるため、create_work_item や list_cycles を呼び出す保存済みプロンプトやスクリプトを変更する必要はありません。これらのツールは公開されなくなりますが、リリース時のパラメーター名（workitem_id ではなく work_item_id）を引き続き使用します。

7 個の名前は、パラメーター（manage_project_archive(archive=False)）によって 2 つの操作を選択していたため、1 組のツールとアクションでは再現できません。これらを呼び出すと、代わりに使用するものが通知されます。get_pql_reference は変更されていません。

設定

認証

変数	必須となるトランスポート	用途
PLANE_API_KEY	stdio	API キー
PLANE_WORKSPACE_SLUG	stdio	対象ワークスペース
PLANE_BASE_URL	任意	Plane API の URL（デフォルトは https://api.plane.so）

リモートトランスポートでは、接続時に認証情報を OAuth フローまたは PAT ヘッダーで渡すため、これらの設定は不要です。

添付ファイルのアップロードに使用するアウトバウンドプロキシ

HTTP_PROXY / HTTPS_PROXY / NO_PROXY（および小文字形式）は、URL からの添付ファイルアップロード取得（upload_from_url）で使用されます。特定のリクエストにプロキシが適用される場合、そのリクエストの SSRF 対策となるのはこのサーバーではなくプロキシです。プロキシが独自にターゲットへ接続し、名前解決を行うため、サーバー自体がターゲットの解決済みアドレスを固定したり検証したりすることはありません。これに応じて NO_PROXY とプロキシのエグレスポリシーを設定してください。

サーバー自体をセルフホストする場合：

変数	用途
PLANE_INTERNAL_BASE_URL	サーバー間呼び出し用の内部 URL。PLANE_BASE_URL より優先されます
REDIS_URL	1 つの接続 URL による OAuth トークンの保存（TLS の場合は redis:// または rediss://）。ホスト／ポートより優先されます
REDIS_HOST / REDIS_PORT	OAuth トークンの保存。インメモリにフォールバックします
PLANE_OAUTH_PROVIDER_*	OAuth クライアントの認証情報とベース URL
MCP_PATH_PREFIX	プロキシの背後に配置する場合の HTTP ルートのパスプレフィックス — /plane で /plane/http/mcp を提供します

OAuth リダイレクト URI

OAuth トランスポートは、各クライアントのリダイレクト URI を許可リストと照合して検証します。 一般的なクライアント（Cursor、VS Code、Claude.ai、ChatGPT コネクター、localhost）はデフォルトで許可されています。

リリースせずに新しいクライアントを登録するには、パターンを追加します。

export PLANE_OAUTH_ALLOWED_REDIRECT_URIS="https://newclient.com/cb,https://other.app/oauth/*"

* は任意のポート、パスセグメント、またはサブドメインに一致します。ホストは固定し、ポートまたはパスのみをワイルドカードにしてください。

ロギング

構造化 JSON 形式です。各ツール呼び出しでは、名前、所要時間、ステータス、および取得可能な場合は不透明なユーザー ID とワークスペースのスラッグがログに記録されます。

export LOG_USER_INFO=false    # also log the display name (PII);
export LOG_PAYLOADS=false    # keep request payloads out of logs; default true

表示名を保持するのは OAuth と PAT のトランスポートのみです。stdio には影響しません。

開発

git clone https://github.com/makeplane/plane-mcp-server
cd plane-mcp-server
uv pip install -e ".[dev]"

ワークスペースに対してサーバーを実行します。

PLANE_API_KEY=... PLANE_WORKSPACE_SLUG=... python -m plane_mcp stdio
python -m plane_mcp http            # port 8211

テスト、フォーマット、Lint を実行します。

pytest                              # no network or credentials needed
ruff format plane_mcp/ tests/       # line length 120
ruff check plane_mcp/ tests/        # rules E, F, I, UP, B

テストスイートは完全にオフラインで実行されます。すべてのリソースのすべてのアクションは、各呼び出しを本物の plane-sdk シグネチャに照らして検証するスタンドインに対して実行されます。plane_mcp/tools/README.md を参照してください。

実行中のサーバーを指定しない限り、ライブ統合テストはスキップされます。

export PLANE_TEST_API_KEY=... PLANE_TEST_WORKSPACE_SLUG=...
export PLANE_TEST_MCP_URL=http://localhost:8211    # optional; this is the default
pytest tests/test_integration.py -v

このテストでは、そのワークスペースに実際のデータを書き込みます。

リポジトリの構成

パス	内容
plane_mcp/__main__.py	エントリーポイント。argv[1] からトランスポートを選択します
plane_mcp/server.py	トランスポートごとのファクトリー
plane_mcp/client.py	認証情報を plane-sdk クライアントに解決します
plane_mcp/auth/	OAuth プロバイダーとヘッダー認証
plane_mcp/tools/	ツールの構成。Plane のリソースごとに 1 つのモジュールがあります
plane_mcp/toolkit/	ツール共通の構成要素
plane_mcp/pql_reference.py	モデルに提供される PQL 構文リファレンス

コントリビューション

プルリクエストを歓迎します。提出前に pytest と ruff check を実行してください。新しいツールには、plane_mcp/tools/README.md に記載されている不変条件を含めてください。

CONTRIBUTING.md と CODE_OF_CONDUCT.md を参照してください。

Node.js サーバーからの移行

@makeplane/plane-mcp-server（Node.js）は非推奨で、保守されていません。この Python 実装がその後継です。

Node.js	Python
PLANE_API_KEY	PLANE_API_KEY
PLANE_API_HOST_URL	PLANE_BASE_URL
PLANE_WORKSPACE_SLUG	PLANE_WORKSPACE_SLUG

クイックスタートの stdio 設定に合わせて、command と args を置き換えてください。

ライセンス

MIT — LICENSE を参照してください。