Plane MCP

A Model Context Protocol server for [Plane](https://plane.so) (self-hosted or Cloud). It lets an LLM client — Claude Desktop, Claude Code, Cursor, etc. — fully drive your Plane workspace: discover projects, and create / read / update / delete / re-organize work items, states, labels, cycles, modules, and comments.

Verified against a self-hosted instance at plane.nzminds.com (workspace nzmt).

What it can do

How Plane's model works (quick mental model)

Workspace (slug, e.g. "nzmt")
 └─ Project (UUID)           ← discover with list_projects
     ├─ Work Items / Issues  ← the tickets; have a UUID + human number (TRAVELXS-391)
     ├─ States               ← the statuses (Backlog/Todo/In Progress/Done…), each a UUID
     ├─ Labels               ← UUIDs
     ├─ Cycles               ← time-boxed sprints
     └─ Modules              ← feature groupings

Everything in a request body is a UUID, not a name. So the normal flow is:

1. list_projects → pick a project UUID.
2. list_states → map "In Progress" → its UUID. list_members / list_labels likewise.
3. Create/update the work item. To change status, set `state` to the target state UUID (or use set_work_item_status).

Most tools take an optional project_id; if omitted they fall back to PLANE_DEFAULT_PROJECT_ID from your .env.

Setup

1. Get an API key

See [SETUP.md](SETUP.md) for step-by-step instructions (Profile Settings → Personal Access Tokens).

2. Configure

cp .env.example .env
# edit .env: PLANE_BASE_URL, PLANE_API_KEY, PLANE_WORKSPACE_SLUG

3. Install

Requires Python ≥ 3.10.

python -m pip install -e .

(or with uv: uv pip install -e .)

4. Run

plane-mcp          # or:  python -m plane_mcp

It speaks MCP over stdio, so you normally don't run it by hand — your MCP client launches it.

Connecting to a client

Claude Desktop / Claude Code

Add to your MCP config (claude_desktop_config.json, or via claude mcp add):

{
  "mcpServers": {
    "plane": {
      "command": "plane-mcp",
      "env": {
        "PLANE_BASE_URL": "https://plane.nzminds.com",
        "PLANE_API_KEY": "plane_api_xxxxxxxx",
        "PLANE_WORKSPACE_SLUG": "nzmt"
      }
    }
  }
}

Or, if you'd rather rely on the .env file, drop the env block and use the absolute interpreter:

{
  "mcpServers": {
    "plane": {
      "command": "python",
      "args": ["-m", "plane_mcp"],
      "cwd": "d:/Govind/Plane MCP"
    }
  }
}

Claude Code one-liner:

claude mcp add plane -- python -m plane_mcp

Example prompts once connected

• "List my projects in Plane."
• "In TravelXS, create a high-priority bug 'Login fails on Safari' and assign it to govind.kumar."
• "Move TRAVELXS-391 to In Progress."
• "Create a cycle 'Sprint 12' from 2026-07-01 to 2026-07-14 and add TRAVELXS-394 and -376 to it."
• "Add a comment to TRAVELXS-308 saying the fix is deployed."

Notes & limits

• Rate limit: 60 requests/min per key. The client auto-retries on 429 with backoff.
• Pagination: list tools follow Plane's cursor pagination and return all results.
• Destructive ops: the hard delete_* tools (project, work item, state, label, cycle, module, comment) are disabled by default. Set PLANE_ALLOW_DELETE=true in .env to expose them. Relationship removals (remove_work_item_from_cycle / _module) are always available since they're reversible.
• Self-hosted path quirk: cycle/module work-item sub-resources are /cycle-issues/ and /module-issues/ (the public docs say work_items, which 404s on self-hosted). This server uses the verified paths.

Project layout

src/plane_mcp/
├── config.py        # env loading & validation
├── client.py        # async HTTP client: pagination, 429 retry, errors
├── server.py        # FastMCP instance + tool registration
├── __main__.py      # entry point (stdio)
└── tools/           # one module per resource
    ├── projects.py  issues.py  states.py  labels.py
    ├── cycles.py    modules.py comments.py members.py

License

MIT