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 的模型上下文协议服务器。为 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

HTTP with 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 with a personal access token — 托管

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 和工作区 slug。

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

测试、格式化、代码检查：

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 语法参考

贡献

欢迎提交拉取请求。请在提交前运行 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。