Plane

官方

官方 Plane MCP 伺服器提供與 Plane API 的整合，支援 Plane 專案、工作項目、週期等的完整 AI 自動化。

GitHub

332

試用此 MCP贊助

你可以用 Plane MCP 做什麼？

建立工作項目 — 請您的助理在專案中建立工作項目，並透過 workitem 工具指定名稱及其他詳細資料。
使用 PQL 查詢工作項目 — 使用 Plane 查詢語言，依狀態、優先順序或指派對象篩選來列出或計算工作項目，例如。
管理週期 — 在專案中封存或更新週期，例如 cycle(action="archive", project_id=..., cycle_id=...)。
存取 PQL 語法參考 — 要求 get_pql_reference 工具以取得完整的 PQL 語法、運算子及實作範例。

文件

Plane MCP 伺服器

一個用於 Plane 的 Model Context Protocol 伺服器。為 AI 代理提供工具，以讀取和管理專案、工作項目、週期、模組、版本、客戶等。

建構於 FastMCP 和官方 plane-sdk 之上。

30 個工具，每個對應一個 Plane 資源，涵蓋 207 項操作
本機或遠端 — stdio、streamable 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

HTTP 搭配 OAuth — 託管

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 傳輸方式。

工具

伺服器提供 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=...)

每個工具的說明會列出其操作及必填和選填參數，因此目錄在呼叫時即可自我說明。

→ 完整工具和操作參考

查詢工作項目

列表、計數和搜尋接受 PQL，即 Plane 的查詢語言：

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 操作提供一個工具。現有整合仍可正常運作：177 個名稱中有 169 個仍可解析到整合後的工具，因此呼叫 create_work_item 或 list_cycles 的已儲存提示或腳本無需變更。這些名稱不再被公告，且保留其原始參數名稱（work_item_id，而非 workitem_id）。

有七個名稱透過參數（manage_project_archive(archive=False)）在兩個操作之間選擇，這是單一工具與操作配對無法重現的；呼叫其中一個會告知其替代方案。get_pql_reference 保持不變。

設定

驗證

變數	必要於	用途
`PLANE_API_KEY`	stdio	API 金鑰
`PLANE_WORKSPACE_SLUG`	stdio	目標工作區
`PLANE_BASE_URL`	選填	Plane API URL（預設 `https://api.plane.so`）

遠端傳輸方式在連線中攜帶憑證 — OAuth 流程或 PAT 標頭 — 且不需要上述任何變數。

自行託管伺服器本身：

變數	用途
`PLANE_INTERNAL_BASE_URL`	伺服器對伺服器呼叫的內部 URL，優先於 `PLANE_BASE_URL`
`REDIS_URL`	OAuth 權杖儲存，作為單一連線 URL（`redis://` 或 `rediss://` 用於 TLS）；優先於主機/連接埠
`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 和工作區 slug。

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 資源一個模組
`plane_mcp/toolkit/`	工具表面的共用建構區塊
`plane_mcp/pql_reference.py`	提供給模型的 PQL 語法參考

貢獻

歡迎提交 Pull Request。請在提交前執行 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`

將 command 和 args 替換為快速開始中的 stdio 設定。

授權

MIT — 請參閱 LICENSE。