Plane

官方

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

GitHub

289

你可以用 Plane MCP 做什麼？

建立工作項目 — 透過 workitem 動作 create 在專案中建立工作項目。
使用 PQL 查詢工作項目 — 使用 workitem 動作 list/count 列出或計算以 PQL 篩選（例如狀態、優先順序）的工作項目。
取得 PQL 參考 — 透過 get_pql_reference 詢問完整的 PQL 語法與運算子。
封存循環 — 使用 cycle 動作 archive 封存循環。

文件

Plane MCP Server

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

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

28 個工具，每個 Plane 資源一個，涵蓋 183 項操作
本機或遠端 — 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 傳輸方式。

工具

伺服器提供 28 個工具，每個資源一個。每個工具接受一個 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_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=true    # also log the display name (PII); default false

只有 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。