Plane

官方

官方 Plane MCP 服务器提供与 Plane API 的集成，支持对 Plane 项目、工作项、周期等进行全面的 AI 自动化。

GitHub

308

试用此 MCP赞助

你可以用 Plane MCP 做什么？

使用 PQL 查询工作项 — 通过 workitem(action="list") 或 count 询问匹配如 state__group = "started" 等过滤器的问题。
创建和管理工作项 — 让助手使用 workitem(action="create") 创建问题，并指定项目、名称及其他字段。
管理周期和模块 — 使用 cycle(action="archive") 或类似操作，直接从聊天中组织冲刺和项目模块。
获取 PQL 语法参考 — 请求 get_pql_reference 以了解构建复杂查询的操作符和示例。
列出和搜索资源 — 使用 30 个可用工具中的 list 操作，枚举项目、周期或工作项。

文档

Plane MCP 服务器

一个用于 Plane 的 Model Context Protocol 服务器。为 AI 代理提供读取和管理项目、工作项、周期、模块、发布、客户等资源的工具。

基于 FastMCP 和官方 plane-sdk 构建。

30 个工具，每个 Plane 资源一个，覆盖 204 个操作
本地或远程 — 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 传输方式。

工具

服务器提供 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 和工作区标识。

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

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

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。