plane-project-mcp
An MCP server for Plane — the open-source project management tool. Point it at your own Plane workspace (cloud or self-hosted) and let any MCP-compatible client (Claude Desktop, Cursor, etc.) list, create, and update your projects, issues, cycles, modules, labels, states, comments, pages, views, and more.
No fleet, no broker, no proxy — you run it, you hold your own Plane API token, it talks straight to the Plane REST API.
Install
Pick one:
# Run without installing (recommended for MCP client use)
uvx plane-project-mcp
# or
pipx run plane-project-mcp
# or install into your environment
pip install plane-project-mcp
Configuration
Self-hosted Plane users MUST set
PLANE_API_URLto their instance (e.g.https://plane.yourcompany.com). It defaults tohttps://api.plane.so(Plane Cloud), so if you don't set it, the server talks to Plane Cloud rather than your own deployment.
Everything is configured via environment variables — there is no config file.
| Variable | Required | Default | Description |
|---|---|---|---|
PLANE_API_KEY |
yes | — | Your Plane API token |
PLANE_API_URL |
no | https://api.plane.so |
Plane API base URL — point this at your self-hosted instance |
PLANE_WORKSPACE_SLUG |
no | — | Default workspace slug (used by list_workspaces when no slug is passed) |
PLANE_MCP_ENABLED_TOOLS |
no | (all tools enabled) | Comma-separated allowlist of tool names to expose |
PLANE_MCP_HTTP |
no | 0 |
Set to 1 to run as an HTTP/SSE service instead of stdio |
PLANE_MCP_HOST |
no | 127.0.0.1 |
Bind host in HTTP mode |
PLANE_MCP_PORT |
no | 8000 |
Bind port in HTTP mode |
If PLANE_API_KEY is missing, the server fails immediately with a
clear error instead of starting half-configured.
Getting a Plane API token
In Plane, go to Workspace Settings -> API Tokens -> Add API token, give it a name, and copy the value. Treat it like a password — anyone holding it can act as your workspace via this server's tools.
Using it with an MCP client
plane-project-mcp speaks stdio by default, which is the transport MCP
clients launch as a subprocess.
Claude Desktop
Add to claude_desktop_config.json:
{
"mcpServers": {
"plane": {
"command": "uvx",
"args": ["plane-project-mcp"],
"env": {
"PLANE_API_KEY": "your-plane-api-token",
"PLANE_WORKSPACE_SLUG": "your-workspace-slug"
}
}
}
}
Cursor
Add to .cursor/mcp.json (project) or ~/.cursor/mcp.json (global):
{
"mcpServers": {
"plane": {
"command": "uvx",
"args": ["plane-project-mcp"],
"env": {
"PLANE_API_KEY": "your-plane-api-token",
"PLANE_WORKSPACE_SLUG": "your-workspace-slug"
}
}
}
}
Generic .mcp.json
Most MCP-capable clients accept the same stdio shape:
{
"mcpServers": {
"plane": {
"command": "python",
"args": ["-m", "plane_mcp.server"],
"env": {
"PLANE_API_KEY": "your-plane-api-token",
"PLANE_API_URL": "https://api.plane.so",
"PLANE_WORKSPACE_SLUG": "your-workspace-slug"
}
}
}
}
Swap command/args for pip install plane-project-mcp + ["-m", "plane_mcp.server"],
or uvx/pipx run + ["plane-project-mcp"] — whichever fits how you installed it.
Self-hosting as an HTTP/SSE service
If you'd rather run plane-project-mcp as a long-lived service (e.g. behind a
reverse proxy) instead of launching it per-client, use --http:
pip install 'plane-project-mcp[http]'
PLANE_API_KEY=... plane-project-mcp --http --host 0.0.0.0 --port 8000
This serves an SSE endpoint at /sse (and /messages/ for posting
client messages), which any MCP client with SSE transport support can
connect to.
Docker
docker build -t plane-project-mcp .
docker run --rm -e PLANE_API_KEY=your-plane-api-token -p 8000:8000 plane-project-mcp
Or with Compose:
cp .env.example .env # fill in PLANE_API_KEY
docker compose up
The bundled docker-compose.yml runs plane-project-mcp --http on port 8000.
Available tools
plane-project-mcp covers the Plane REST API surface: workspaces, projects,
project members, issues (create/read/update/delete, comments,
attachments, links, relations, sub-issues, activity), labels, states,
cycles (+ cycle-issue membership, transfers), modules (+ module-issue
membership), pages, project views, workspace views, intake/inbox
issues, estimates, and webhooks.
By default every tool is enabled. To restrict a deployment to a subset
(e.g. read-only, or issues-only), set PLANE_MCP_ENABLED_TOOLS to a
comma-separated list of tool names, for example:
export PLANE_MCP_ENABLED_TOOLS=list_projects,list_issues,get_issue,create_issue,update_issue
Destructive operations (delete_*, remove_*) always require an
explicit confirm: true argument alongside the exact target ID —
there is no "delete everything" shortcut.
Development
git clone https://github.com/Etumos/plane-project-mcp
cd plane-project-mcp
python3 -m venv .venv && source .venv/bin/activate
pip install -e ".[dev,http]"
python -m pytest
Smoke-test the server locally (uses a dummy token, makes no network calls):
PLANE_API_KEY=dummy python -m plane_mcp.server --help
License
MIT — see LICENSE.
Metadata
Release files for plane-project-mcp 0.1.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| plane_project_mcp-0.1.1.tar.gz | 18.8 kB | Without provenance | Details for plane_project_mcp-0.1.1.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| plane_project_mcp-0.1.1-py3-none-any.whl | Python 3 | none | any | Details for plane_project_mcp-0.1.1-py3-none-any.whl |
Total release size: 37.6 kB
Release files / plane_project_mcp-0.1.1.tar.gz
| Download URL | plane_project_mcp-0.1.1.tar.gz |
|---|---|
| Size | 18.8 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
0321041ba736d6b7ed215e5e8e320f6a669df2132adbf02bc6f411cb1e0cc3b4
|
|
BLAKE2b-256 checksum How to use checksums |
0019bfbb26ea95236e63d8d33baeac9063466cba2575cb2e6962419b1e2dd39e
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.11.2
|
Release files / plane_project_mcp-0.1.1-py3-none-any.whl
| Download URL | plane_project_mcp-0.1.1-py3-none-any.whl |
|---|---|
| Size | 18.9 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
1b13ff041faed8d3e9da0a0c94b50c8fc52dd93fdb144511f453b5339df7b82a
|
|
BLAKE2b-256 checksum How to use checksums |
426e4d310a4f853a8e4b7479fb0855e4d6561a79f80354d587ca24aba05fa2ed
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.11.2
|
Security for plane-project-mcp 0.1.1
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.