Plane MCP Server

官方

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

GitHub
255

文件

Plane MCP 伺服器

一個用於 Plane 整合的模型上下文協定 (MCP) 伺服器。此伺服器提供工具和資源，讓 AI 代理程式能與 Plane 互動。

功能特色

  • 🔧 Plane 整合：與 Plane API 和服務互動
  • 🔌 多重傳輸：支援 stdio、SSE 和可串流的 HTTP 傳輸
  • 🌐 遠端與本機：可作為本機和遠端服務運作
  • 🛠️ 可擴展：易於新增工具和資源

使用方式

伺服器支援三種傳輸方法。我們建議使用 uvx，因為它無需安裝。

需求：

  • Python 3.10+（用於 stdio 傳輸，透過 uvx）
  • Node.js 22+（用於遠端傳輸，透過 npx）

1. Stdio 傳輸（本機使用）

MCP 用戶端設定（使用 uvx - 建議）：

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

2. 使用 OAuth 的遠端 HTTP 傳輸

使用 OAuth 驗證連線到託管的 Plane MCP 伺服器。

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

MCP 用戶端設定（適用於沒有原生遠端 MCP 支援的工具，如 Claude Desktop）：

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

注意：連線到遠端伺服器時，OAuth 驗證將自動處理。

3. 使用 PAT 權杖的遠端 HTTP 傳輸

使用個人存取權杖 (PAT) 連線到託管的 Plane MCP 伺服器。

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

標頭：

  • Authorization: Bearer <PAT_TOKEN>
  • X-Workspace-slug: <SLUG>

MCP 用戶端設定（適用於沒有原生遠端 MCP 支援的工具，如 Claude Desktop）：

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

4. SSE 傳輸（舊版）

⚠️ 舊版傳輸：SSE（伺服器傳送事件）傳輸是為了向下相容而保留。新的實作應改用 HTTP 傳輸（第 2 或第 3 節）。

使用 OAuth 驗證透過伺服器傳送事件連線到託管的 Plane MCP 伺服器。

URL：https://mcp.plane.so/sse

MCP 用戶端設定（適用於支援 SSE 傳輸的工具）：

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

注意：連線到遠端伺服器時，OAuth 驗證將自動處理。此傳輸已棄用，建議改用 HTTP 傳輸。

設定

驗證

伺服器需要透過環境變數進行驗證：

  • PLANE_BASE_URL：Plane API 的基礎 URL（預設：https://api.plane.so）- 選用
  • PLANE_API_KEY：用於驗證的 API 金鑰（stdio 傳輸為必要）
  • PLANE_WORKSPACE_SLUG：工作區 slug 識別碼（stdio 傳輸為必要）
  • PLANE_ACCESS_TOKEN：用於驗證的存取權杖（API 金鑰的替代方案）

範例（用於 stdio 傳輸）：

export PLANE_BASE_URL="https://api.plane.so"
export PLANE_API_KEY="your-api-key"
export PLANE_WORKSPACE_SLUG="your-workspace-slug"

注意：對於遠端 HTTP 傳輸（OAuth 或 PAT），驗證是透過連線方法（OAuth 流程或 PAT 標頭）處理，不需要這些環境變數。

OAuth 重新導向 URI

對於 OAuth HTTP/SSE 傳輸，伺服器會根據允許清單驗證每個用戶端的重新導向 URI。常見的 MCP 用戶端（Cursor、VS Code、Claude.ai、ChatGPT 連接器、localhost）預設為允許。

若要在不變更程式碼或發佈版本的情況下加入新的用戶端，可透過環境變數附加額外模式：

  • PLANE_OAUTH_ALLOWED_REDIRECT_URIS：以逗號分隔的重新導向 URI 模式，會附加到內建允許清單。
export PLANE_OAUTH_ALLOWED_REDIRECT_URIS="https://newclient.com/cb,https://other.app/oauth/*"

模式支援 glob 比對（* 可匹配任何連接埠、路徑區段或子網域）。為確保安全，請固定主機，僅對連接埠/路徑使用萬用字元。

記錄

伺服器會發出結構化的 JSON 記錄。每個工具呼叫都會記錄其工具名稱、持續時間、狀態，以及（若可用）不透明的使用者 ID 和工作區 slug。

  • LOG_USER_INFO：當設為 true 時，會在記錄中包含使用者資訊（PII，例如顯示名稱）以及不透明的使用者 ID。預設為 false，因此除非明確選擇加入，否則絕不會記錄 PII。只有 OAuth 和 PAT（標頭）HTTP 傳輸會攜帶顯示名稱；stdio 不受影響。
export LOG_USER_INFO="true"

可用工具

伺服器提供與 Plane 互動的全面工具。所有工具都使用 Plane SDK 中的 Pydantic 模型，以確保型別安全和驗證。

專案

工具名稱說明
list_projects列出工作區中的所有專案，可選擇分頁和篩選
create_project建立新專案，包含名稱、識別碼和選用設定
retrieve_project透過 ID 擷取專案
update_project使用部分資料更新專案
delete_project透過 ID 刪除專案
get_project_worklog_summary取得專案的工作記錄摘要
get_project_members取得專案的所有成員
update_project_features更新專案的功能設定

工作項目

工具名稱說明
list_work_items列出專案中的所有工作項目，可選擇篩選和分頁
create_work_item建立新工作項目，包含名稱、指派者、標籤和其他屬性
retrieve_work_item透過 ID 擷取工作項目，可選擇欄位展開
retrieve_work_item_by_identifier透過專案識別碼和議題序號擷取工作項目
update_work_item使用部分資料更新工作項目
delete_work_item透過 ID 刪除工作項目
search_work_items使用查詢字串跨工作區搜尋工作項目

週期

工具名稱說明
list_cycles列出專案中的週期（設定 archived=true 以檢視已封存）
create_cycle建立新週期，包含名稱、日期和擁有者
retrieve_cycle透過 ID 擷取週期
update_cycle使用部分資料更新週期
delete_cycle透過 ID 刪除週期
manage_cycle_work_items在週期中新增和/或移除工作項目
list_cycle_work_items列出週期中的工作項目
transfer_cycle_work_items將工作項目從一個週期轉移到另一個週期
manage_cycle_archive封存或取消封存週期

模組

工具名稱說明
list_modules列出專案中的模組（設定 archived=true 以檢視已封存）
create_module建立新模組，包含名稱、日期、狀態和成員
retrieve_module透過 ID 擷取模組
update_module使用部分資料更新模組
delete_module透過 ID 刪除模組
manage_module_work_items在模組中新增和/或移除工作項目
list_module_work_items列出模組中的工作項目
manage_module_archive封存或取消封存模組

倡議

工具名稱說明
list_initiatives列出工作區中的所有倡議
create_initiative建立新倡議，包含名稱、日期、狀態和負責人
retrieve_initiative透過 ID 擷取倡議
update_initiative使用部分資料更新倡議
delete_initiative透過 ID 刪除倡議

接收工作項目

工具名稱說明
list_intake_work_items列出專案中的所有接收工作項目，可選擇分頁
create_intake_work_item在專案中建立新的接收工作項目
retrieve_intake_work_item透過工作項目 ID 擷取接收工作項目，可選擇欄位展開
update_intake_work_item使用部分資料更新接收工作項目
delete_intake_work_item透過工作項目 ID 刪除接收工作項目

工作項目屬性

工具名稱說明
list_work_item_properties列出工作項目類型的工作項目屬性
create_work_item_property建立新的工作項目屬性，包含類型、設定和驗證規則
retrieve_work_item_property透過 ID 擷取工作項目屬性
update_work_item_property使用部分資料更新工作項目屬性
delete_work_item_property透過 ID 刪除工作項目屬性

里程碑

工具名稱說明
list_milestones列出專案中的所有里程碑
create_milestone建立新的里程碑
retrieve_milestone透過 ID 擷取里程碑
update_milestone透過 ID 更新里程碑
delete_milestone透過 ID 刪除里程碑
manage_milestone_work_items在里程碑中新增和/或移除工作項目
list_milestone_work_items列出里程碑中的工作項目

標籤

工具名稱說明
list_labels列出專案中的所有標籤
create_label建立新標籤
retrieve_label透過 ID 擷取標籤
update_label透過 ID 更新標籤
delete_label透過 ID 刪除標籤

狀態

工具名稱說明
list_states列出專案中的所有狀態
create_state建立新狀態
retrieve_state透過 ID 擷取狀態
update_state透過 ID 更新狀態
delete_state透過 ID 刪除狀態

工作項目留言

工具名稱說明
list_work_item_comments列出工作項目的留言
retrieve_work_item_comment擷取工作項目的特定留言
create_work_item_comment為工作項目建立留言
update_work_item_comment更新工作項目的留言
delete_work_item_comment刪除工作項目的留言

工作項目連結

工具名稱說明
list_work_item_links列出工作項目的連結
retrieve_work_item_link擷取工作項目的特定連結
create_work_item_link為工作項目建立連結
update_work_item_link更新工作項目的連結
delete_work_item_link刪除工作項目的連結

工作項目類型

工具名稱說明
list_work_item_types列出專案中的所有工作項目類型
create_work_item_type建立新的工作項目類型
retrieve_work_item_type透過 ID 擷取工作項目類型
update_work_item_type透過 ID 更新工作項目類型
delete_work_item_type透過 ID 刪除工作項目類型
import_work_item_types_to_project將工作區層級的工作項目類型批次連結到專案
resolve_work_item_type為專案尋找或建立具名類型，自動處理工作區與專案範圍及匯入

工作項目關聯

工具名稱說明
list_work_item_relations列出工作項目的關聯
create_work_item_relation為工作項目建立關聯
remove_work_item_relation從工作項目移除關聯

工作項目關聯定義

工具名稱說明
list_work_item_relation_definitions列出工作區自訂關聯定義
create_work_item_relation_definition建立工作區關聯定義
update_work_item_relation_definition更新關聯定義
delete_work_item_relation_definition刪除關聯定義

工作項目活動

工具名稱說明
list_work_item_activities列出工作項目的活動
retrieve_work_item_activity擷取工作項目的特定活動

工作記錄

工具名稱說明
list_work_logs列出工作項目的工作記錄
create_work_log為工作項目建立工作記錄
update_work_log更新工作項目的工作記錄
delete_work_log刪除工作項目的工作記錄

頁面

工具名稱說明
list_pages列出頁面（工作區，或若提供 project_id 則為專案的）
retrieve_page透過 ID 擷取頁面（工作區，或若提供 project_id 則為專案的）
create_page建立工作區或專案頁面

工作區

工具名稱說明
get_workspace_members取得目前工作區的所有成員
get_features取得功能旗標（工作區，或若提供 project_id 則為專案的）
update_workspace_features更新目前工作區的功能

使用者

工具名稱說明
get_me取得目前已驗證使用者的資訊

工具總數：超過 100 個工具，涵蓋 20 個類別

開發

執行測試

pytest

程式碼格式化

black plane_mcp/
ruff check plane_mcp/

授權

MIT 授權條款 - 詳情請參閱 LICENSE 檔案。

貢獻

歡迎貢獻！請隨時提交 Pull Request。

棄用通知

⚠️ 基於 Node.js 的 plane-mcp-server 已棄用，不再維護。

此儲存庫代表 Plane MCP 伺服器基於 Python+FastMCP 的全新實作。如果您之前使用的是 Node.js 版本，請遷移至此 Python 版本以獲得持續的支援與更新。

新的實作提供：

  • 透過 Pydantic 模型提升型別安全
  • 藉由 FastMCP 改善效能
  • 增強的工具涵蓋範圍
  • 積極的維護與開發

如需遷移協助，請參考本 README 中的設定範例，或開啟 issue 尋求支援。

舊的 Node.js 設定（已棄用）：

如果您之前使用的是基於 Node.js 的 @makeplane/plane-mcp-server，您的設定看起來像這樣：

{
  "mcpServers": {
    "plane": {
      "command": "npx",
      "args": [
        "-y",
        "@makeplane/plane-mcp-server"
      ],
      "env": {
        "PLANE_API_KEY": "<YOUR_API_KEY>",
        "PLANE_API_HOST_URL": "<HOST_URL_FOR_SELF_HOSTED>",
        "PLANE_WORKSPACE_SLUG": "<YOUR_WORKSPACE_SLUG>"
      }
    }
  }
}

請遷移至上方「使用方法」章節中所示的新 Python 設定。