Skip to content
Back to search

plane-mcp-server

Plane's Official Model Context Protocol Server πŸ”Œ ⌨️ πŸ”₯

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/makeplane/plane-mcp-server with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/makeplane/plane-mcp-server'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/makeplane--plane-mcp-server/badge.svg)](/listings/makeplane--plane-mcp-server)

HTML

<a href="/listings/makeplane--plane-mcp-server"><img src="/api/listings/makeplane--plane-mcp-server/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Get an API key from Plane: **Workspace Settings β†’ API tokens**.

Add this to your MCP client's configuration:

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

`uvx` needs no install step. Requires Python 3.10+.

For a self-hosted Plane, add `"PLANE_BASE_URL": "https://plane.example.com"`.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md Β· README Β· 271 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. # Plane MCP Server
  2. A [Model Context Protocol](https://modelcontextprotocol.io) server for
  3. [Plane](https://plane.so). Gives an AI agent tools to read and manage projects,
  4. work items, cycles, modules, releases, customers and more.
  5. Built on [FastMCP](https://github.com/jlowin/fastmcp) and the official
  6. [`plane-sdk`](https://pypi.org/project/plane-sdk/).
  7. - **30 tools**, one per Plane resource, covering 207 operations
  8. - **Local or remote** β€” stdio, streamable HTTP, SSE
  9. - **OAuth or API key** authentication
  10. ## Quick start
  11. Get an API key from Plane: **Workspace Settings β†’ API tokens**.
  12. Add this to your MCP client's configuration:
  13. ```json
  14. {
  15. "mcpServers": {
  16. "plane": {
  17. "command": "uvx",
  18. "args": ["plane-mcp-server", "stdio"],
  19. "env": {
  20. "PLANE_API_KEY": "<your-api-key>",
  21. "PLANE_WORKSPACE_SLUG": "<your-workspace-slug>"
  22. }
  23. }
  24. }
  25. }
  26. ```
  27. `uvx` needs no install step. Requires Python 3.11+.
  28. For a self-hosted Plane, add `"PLANE_BASE_URL": "https://plane.example.com"`.
  29. ## Transports
  30. ### stdio β€” local
  31. Runs as a subprocess of your MCP client. Configuration as shown above; needs
  32. `PLANE_API_KEY` and `PLANE_WORKSPACE_SLUG`.
  33. ```bash
  34. PLANE_API_KEY=... PLANE_WORKSPACE_SLUG=... uvx plane-mcp-server stdio
  35. ```
  36. ### HTTP with OAuth β€” hosted
  37. `https://mcp.plane.so/http/mcp`
  38. The OAuth flow is handled on connect; no credentials in your config. For clients
  39. without native remote MCP support, bridge with `mcp-remote`:
  40. ```json
  41. {
  42. "mcpServers": {
  43. "plane": {
  44. "command": "npx",
  45. "args": ["mcp-remote@latest", "https://mcp.plane.so/http/mcp"]
  46. }
  47. }
  48. }
  49. ```
  50. Requires Node.js 22+.
  51. ### HTTP with a personal access token β€” hosted
  52. `https://mcp.plane.so/http/api-key/mcp`
  53. | Header | Value |
  54. |---|---|
  55. | `Authorization` | `Bearer <PAT>` |
  56. | `X-Workspace-slug` | `<workspace-slug>` |
  57. ```json
  58. {
  59. "mcpServers": {
  60. "plane": {
  61. "command": "npx",
  62. "args": ["mcp-remote@latest", "https://mcp.plane.so/http/api-key/mcp"],
  63. "headers": {
  64. "Authorization": "Bearer <PAT>",
  65. "X-Workspace-slug": "<workspace-slug>"
  66. }
  67. }
  68. }
  69. }
  70. ```
  71. ### SSE β€” deprecated
  72. `https://mcp.plane.so/sse` is maintained for backward compatibility only. Use an
  73. HTTP transport instead.
  74. ## Tools
  75. The server advertises 30 tools, one per resource. Each takes an `action`
  76. parameter that selects the operation:
  77. ```python
  78. workitem(action="create", project_id=..., name="Fix login")
  79. workitem(action="list", project_id=..., pql='state__group = "started"')
  80. cycle(action="archive", project_id=..., cycle_id=...)
  81. ```
  82. Every tool's description lists its actions with their required and optional
  83. parameters, so the catalogue is self-documenting at call time.
  84. **β†’ [Full tool and action reference](plane_mcp/tools/README.md)**
  85. ### Querying work items
  86. List, count and search accept **PQL**, Plane's query language:
  87. ```python
  88. workitem(action="list", project_id=..., pql='state__group = "started" AND priority = "urgent"')
  89. workitem(action="count", pql='assignees__id = "<member id>"', group_by="state_id")
  90. ```
  91. Call `get_pql_reference` for the full syntax, operators and worked examples.
  92. ### Upgrading from the per-operation tools
  93. Earlier releases exposed one tool per API operation. **Existing integrations keep
  94. working**: 169 of those 177 names still resolve to the consolidated tool, so a
  95. saved prompt or script calling `create_work_item` or `list_cycles` needs no
  96. change. They are no longer advertised, and they keep the parameter names they
  97. shipped with (`work_item_id`, not `workitem_id`).
  98. Seven names chose between two operations with a parameter
  99. (`manage_project_archive(archive=False)`), which one tool-and-action pair cannot
  100. reproduce; calling one tells you its replacement. `get_pql_reference` is
  101. unchanged.
  102. ## Configuration
  103. ### Authentication
  104. | Variable | Required for | Purpose |
  105. |---|---|---|
  106. | `PLANE_API_KEY` | stdio | API key |
  107. | `PLANE_WORKSPACE_SLUG` | stdio | Target workspace |
  108. | `PLANE_BASE_URL` | optional | Plane API URL (default `https://api.plane.so`) |
  109. The remote transports carry credentials in the connection β€” the OAuth flow or the
  110. PAT headers β€” and need none of these.
  111. ### Outbound proxy for attachment uploads
  112. `HTTP_PROXY` / `HTTPS_PROXY` / `NO_PROXY` (and their lowercase forms) are honored
  113. for the attachment-upload-from-URL fetch (`upload_from_url`). When a proxy
  114. applies to a given request, **the proxy β€” not this server β€” is that request's
  115. SSRF control**: the server does not pin or validate the target's resolved
  116. address itself, since the proxy connects to and resolves the target
  117. independently. Scope `NO_PROXY` and proxy egress policy accordingly.
  118. Self-hosting the server itself:
  119. | Variable | Purpose |
  120. |---|---|
  121. | `PLANE_INTERNAL_BASE_URL` | Internal URL for server-to-server calls, preferred over `PLANE_BASE_URL` |
  122. | `REDIS_URL` | OAuth token storage as one connection URL (`redis://` or `rediss://` for TLS); wins over host/port |
  123. | `REDIS_HOST` / `REDIS_PORT` | OAuth token storage; falls back to in-memory |
  124. | `PLANE_OAUTH_PROVIDER_*` | OAuth client credentials and base URL |
  125. | `MCP_PATH_PREFIX` | Path prefix for the HTTP routes, when mounted behind a proxy β€” `/plane` serves `/plane/http/mcp` |
  126. ### OAuth redirect URIs
  127. The OAuth transports validate each client's redirect URI against an allowlist.
  128. Common clients (Cursor, VS Code, Claude.ai, ChatGPT connectors, localhost) are
  129. allowed by default.
  130. To onboard a new client without a release, append patterns:
  131. ```bash
  132. export PLANE_OAUTH_ALLOWED_REDIRECT_URIS="https://newclient.com/cb,https://other.app/oauth/*"
  133. ```
  134. `*` matches any port, path segment or subdomain. Keep the host pinned and
  135. wildcard only the port or path.
  136. ### Logging
  137. Structured JSON. Each tool call logs its name, duration, status and β€” when
  138. available β€” an opaque user id and the workspace slug.
  139. ```bash
  140. export LOG_USER_INFO=false # also log the display name (PII);
  141. export LOG_PAYLOADS=false # keep request payloads out of logs; default true
  142. ```
  143. Only the OAuth and PAT transports carry a display name; stdio is unaffected.
  144. ## Development
  145. ```bash
  146. git clone https://github.com/makeplane/plane-mcp-server
  147. cd plane-mcp-server
  148. uv pip install -e ".[dev]"
  149. ```
  150. Run the server against a workspace:
  151. ```bash
  152. PLANE_API_KEY=... PLANE_WORKSPACE_SLUG=... python -m plane_mcp stdio
  153. python -m plane_mcp http # port 8211
  154. ```
  155. Tests, format, lint:
  156. ```bash
  157. pytest # no network or credentials needed
  158. ruff format plane_mcp/ tests/ # line length 120
  159. ruff check plane_mcp/ tests/ # rules E, F, I, UP, B
  160. ```
  161. The suite runs fully offline β€” every action of every resource is
  162. executed against a stand-in that binds each call against the genuine `plane-sdk`
  163. signature. See [`plane_mcp/tools/README.md`](plane_mcp/tools/README.md#tests).
  164. Live integration tests are skipped unless you point them at a running server:
  165. ```bash
  166. export PLANE_TEST_API_KEY=... PLANE_TEST_WORKSPACE_SLUG=...
  167. export PLANE_TEST_MCP_URL=http://localhost:8211 # optional; this is the default
  168. pytest tests/test_integration.py -v
  169. ```
  170. They write real data to that workspace.
  171. ### Repository layout
  172. | Path | Contents |
  173. |---|---|
  174. | `plane_mcp/__main__.py` | entry point; picks the transport from `argv[1]` |
  175. | `plane_mcp/server.py` | one factory per transport |
  176. | `plane_mcp/client.py` | resolves credentials into a `plane-sdk` client |
  177. | `plane_mcp/auth/` | OAuth provider and header auth |
  178. | `plane_mcp/tools/` | the tool surface: one module per Plane resource |
  179. | `plane_mcp/toolkit/` | shared building blocks for the tool surface |
  180. | `plane_mcp/pql_reference.py` | PQL syntax reference served to models |
  181. ## Contributing
  182. Pull requests welcome. Please run `pytest` and `ruff check` before submitting; new
  183. tools should come with the invariants described in
  184. [`plane_mcp/tools/README.md`](plane_mcp/tools/README.md).
  185. See [CONTRIBUTING.md](CONTRIBUTING.md) and [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md).
  186. ## Migrating from the Node.js server
  187. `@makeplane/plane-mcp-server` (Node.js) is deprecated and unmaintained. This
  188. Python implementation replaces it.
  189. | Node.js | Python |
  190. |---|---|
  191. | `PLANE_API_KEY` | `PLANE_API_KEY` |
  192. | `PLANE_API_HOST_URL` | `PLANE_BASE_URL` |
  193. | `PLANE_WORKSPACE_SLUG` | `PLANE_WORKSPACE_SLUG` |
  194. Replace the `command` and `args` with the stdio configuration in
  195. [Quick start](#quick-start).
  196. ## License
  197. MIT β€” see [LICENSE](LICENSE).

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.