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.
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
Markdown
[](/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
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.
- # Plane MCP Server
- A [Model Context Protocol](https://modelcontextprotocol.io) server for
- [Plane](https://plane.so). Gives an AI agent tools to read and manage projects,
- work items, cycles, modules, releases, customers and more.
- Built on [FastMCP](https://github.com/jlowin/fastmcp) and the official
- [`plane-sdk`](https://pypi.org/project/plane-sdk/).
- - **30 tools**, one per Plane resource, covering 207 operations
- - **Local or remote** β stdio, streamable HTTP, SSE
- - **OAuth or API key** authentication
- ## Quick start
- Get an API key from Plane: **Workspace Settings β API tokens**.
- Add this to your MCP client's configuration:
- ```json
- {
- "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.11+.
- For a self-hosted Plane, add `"PLANE_BASE_URL": "https://plane.example.com"`.
- ## Transports
- ### stdio β local
- Runs as a subprocess of your MCP client. Configuration as shown above; needs
- `PLANE_API_KEY` and `PLANE_WORKSPACE_SLUG`.
- ```bash
- PLANE_API_KEY=... PLANE_WORKSPACE_SLUG=... uvx plane-mcp-server stdio
- ```
- ### HTTP with OAuth β hosted
- `https://mcp.plane.so/http/mcp`
- The OAuth flow is handled on connect; no credentials in your config. For clients
- without native remote MCP support, bridge with `mcp-remote`:
- ```json
- {
- "mcpServers": {
- "plane": {
- "command": "npx",
- "args": ["mcp-remote@latest", "https://mcp.plane.so/http/mcp"]
- }
- }
- }
- ```
- Requires Node.js 22+.
- ### HTTP with a personal access token β hosted
- `https://mcp.plane.so/http/api-key/mcp`
- | Header | Value |
- |---|---|
- | `Authorization` | `Bearer <PAT>` |
- | `X-Workspace-slug` | `<workspace-slug>` |
- ```json
- {
- "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 β deprecated
- `https://mcp.plane.so/sse` is maintained for backward compatibility only. Use an
- HTTP transport instead.
- ## Tools
- The server advertises 30 tools, one per resource. Each takes an `action`
- parameter that selects the operation:
- ```python
- workitem(action="create", project_id=..., name="Fix login")
- workitem(action="list", project_id=..., pql='state__group = "started"')
- cycle(action="archive", project_id=..., cycle_id=...)
- ```
- Every tool's description lists its actions with their required and optional
- parameters, so the catalogue is self-documenting at call time.
- **β [Full tool and action reference](plane_mcp/tools/README.md)**
- ### Querying work items
- List, count and search accept **PQL**, Plane's query language:
- ```python
- workitem(action="list", project_id=..., pql='state__group = "started" AND priority = "urgent"')
- workitem(action="count", pql='assignees__id = "<member id>"', group_by="state_id")
- ```
- Call `get_pql_reference` for the full syntax, operators and worked examples.
- ### Upgrading from the per-operation tools
- Earlier releases exposed one tool per API operation. **Existing integrations keep
- working**: 169 of those 177 names still resolve to the consolidated tool, so a
- saved prompt or script calling `create_work_item` or `list_cycles` needs no
- change. They are no longer advertised, and they keep the parameter names they
- shipped with (`work_item_id`, not `workitem_id`).
- Seven names chose between two operations with a parameter
- (`manage_project_archive(archive=False)`), which one tool-and-action pair cannot
- reproduce; calling one tells you its replacement. `get_pql_reference` is
- unchanged.
- ## Configuration
- ### Authentication
- | Variable | Required for | Purpose |
- |---|---|---|
- | `PLANE_API_KEY` | stdio | API key |
- | `PLANE_WORKSPACE_SLUG` | stdio | Target workspace |
- | `PLANE_BASE_URL` | optional | Plane API URL (default `https://api.plane.so`) |
- The remote transports carry credentials in the connection β the OAuth flow or the
- PAT headers β and need none of these.
- ### Outbound proxy for attachment uploads
- `HTTP_PROXY` / `HTTPS_PROXY` / `NO_PROXY` (and their lowercase forms) are honored
- for the attachment-upload-from-URL fetch (`upload_from_url`). When a proxy
- applies to a given request, **the proxy β not this server β is that request's
- SSRF control**: the server does not pin or validate the target's resolved
- address itself, since the proxy connects to and resolves the target
- independently. Scope `NO_PROXY` and proxy egress policy accordingly.
- Self-hosting the server itself:
- | Variable | Purpose |
- |---|---|
- | `PLANE_INTERNAL_BASE_URL` | Internal URL for server-to-server calls, preferred over `PLANE_BASE_URL` |
- | `REDIS_URL` | OAuth token storage as one connection URL (`redis://` or `rediss://` for TLS); wins over host/port |
- | `REDIS_HOST` / `REDIS_PORT` | OAuth token storage; falls back to in-memory |
- | `PLANE_OAUTH_PROVIDER_*` | OAuth client credentials and base URL |
- | `MCP_PATH_PREFIX` | Path prefix for the HTTP routes, when mounted behind a proxy β `/plane` serves `/plane/http/mcp` |
- ### OAuth redirect URIs
- The OAuth transports validate each client's redirect URI against an allowlist.
- Common clients (Cursor, VS Code, Claude.ai, ChatGPT connectors, localhost) are
- allowed by default.
- To onboard a new client without a release, append patterns:
- ```bash
- export PLANE_OAUTH_ALLOWED_REDIRECT_URIS="https://newclient.com/cb,https://other.app/oauth/*"
- ```
- `*` matches any port, path segment or subdomain. Keep the host pinned and
- wildcard only the port or path.
- ### Logging
- Structured JSON. Each tool call logs its name, duration, status and β when
- available β an opaque user id and the workspace slug.
- ```bash
- export LOG_USER_INFO=false # also log the display name (PII);
- export LOG_PAYLOADS=false # keep request payloads out of logs; default true
- ```
- Only the OAuth and PAT transports carry a display name; stdio is unaffected.
- ## Development
- ```bash
- git clone https://github.com/makeplane/plane-mcp-server
- cd plane-mcp-server
- uv pip install -e ".[dev]"
- ```
- Run the server against a workspace:
- ```bash
- PLANE_API_KEY=... PLANE_WORKSPACE_SLUG=... python -m plane_mcp stdio
- python -m plane_mcp http # port 8211
- ```
- Tests, format, lint:
- ```bash
- 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
- ```
- The suite runs fully offline β every action of every resource is
- executed against a stand-in that binds each call against the genuine `plane-sdk`
- signature. See [`plane_mcp/tools/README.md`](plane_mcp/tools/README.md#tests).
- Live integration tests are skipped unless you point them at a running server:
- ```bash
- 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
- ```
- They write real data to that workspace.
- ### Repository layout
- | Path | Contents |
- |---|---|
- | `plane_mcp/__main__.py` | entry point; picks the transport from `argv[1]` |
- | `plane_mcp/server.py` | one factory per transport |
- | `plane_mcp/client.py` | resolves credentials into a `plane-sdk` client |
- | `plane_mcp/auth/` | OAuth provider and header auth |
- | `plane_mcp/tools/` | the tool surface: one module per Plane resource |
- | `plane_mcp/toolkit/` | shared building blocks for the tool surface |
- | `plane_mcp/pql_reference.py` | PQL syntax reference served to models |
- ## Contributing
- Pull requests welcome. Please run `pytest` and `ruff check` before submitting; new
- tools should come with the invariants described in
- [`plane_mcp/tools/README.md`](plane_mcp/tools/README.md).
- See [CONTRIBUTING.md](CONTRIBUTING.md) and [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md).
- ## Migrating from the Node.js server
- `@makeplane/plane-mcp-server` (Node.js) is deprecated and unmaintained. This
- Python implementation replaces it.
- | Node.js | Python |
- |---|---|
- | `PLANE_API_KEY` | `PLANE_API_KEY` |
- | `PLANE_API_HOST_URL` | `PLANE_BASE_URL` |
- | `PLANE_WORKSPACE_SLUG` | `PLANE_WORKSPACE_SLUG` |
- Replace the `command` and `args` with the stdio configuration in
- [Quick start](#quick-start).
- ## License
- MIT β see [LICENSE](LICENSE).
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If itβs helped, pass it on.