plane-mcp-server

An MCP (Model Context Protocol) server for self-hosted Plane (Community Edition). It gives Claude 56 tools covering projects, work items, states, labels, cycles, modules, comments, activity history, links, members, and intake triage, enough to act as a project manager across every project in your Plane workspace, from a local chat session.

Built against Plane's public REST API (/api/v1), documented at developers.plane.so. Community Edition covers projects, work items, cycles, modules, intake, and states/labels — this server sticks to that surface. Epics, initiatives, teamspaces, and customers are Plane Commercial/Cloud-only features and are intentionally not included.

Setup

1. Generate a Plane API key

In your Plane instance: Profile Settings → Personal Access Tokens → Add personal access token.

2. Install dependencies and build

cd plane-mcp-server
npm install
npm run build

3. Configure environment variables

Copy .env.example to .env for reference, but note: MCP clients (Claude Desktop, Claude Code) pass environment variables directly in their config, not via a .env file loaded by this process.

Variable	Required	Description
PLANE_BASE_URL	Yes	Base URL of your self-hosted instance, e.g. https://plane.mycompany.com (no /api/v1 suffix).
PLANE_API_KEY	Yes	Personal Access Token from step 1.
PLANE_WORKSPACE_SLUG	No	Default workspace slug (from your Plane URL). If set, tools' workspace_slug argument becomes optional.

4. Add to your MCP client

Claude Code (claude mcp add or edit .mcp.json):

{
  "mcpServers": {
    "plane": {
      "command": "node",
      "args": ["/absolute/path/to/plane-mcp-server/dist/index.js"],
      "env": {
        "PLANE_BASE_URL": "https://plane.mycompany.com",
        "PLANE_API_KEY": "plane_api_xxxxxxxxxxxxxxxxxxxx",
        "PLANE_WORKSPACE_SLUG": "acme"
      }
    }
  }
}

Claude Desktop (claude_desktop_config.json): same mcpServers block as above.

Restart the client after editing config. You should see the plane server connect with 56 tools available.

What it can do

• Projects — list/get/create/update/archive/delete, keeping track of every project in a workspace at once.
• Work items (issues) — full CRUD, lookup by UUID or human identifier (ENG-123), free-text search, and advanced structured-filter search (by state, priority, assignee, labels).
• States & labels — inspect and manage each project's workflow columns and tags.
• Cycles (sprints) — create/update/delete, assign or remove work items, read progress counts for status reporting.
• Modules — same lifecycle as cycles, for longer-running feature groupings.
• Comments & activity — read/write discussion threads, read the audit trail of field changes on a work item.
• Links — attach PRs/docs/designs to a work item.
• Members — resolve people's names/emails to UUIDs, staff projects, change roles.
• Intake — triage incoming requests (accept/reject/snooze/duplicate) before they hit the backlog.

Every list/get tool accepts response_format: "markdown" | "json" (markdown by default, for readability; json for further programmatic use), and every tool that needs a workspace defaults to PLANE_WORKSPACE_SLUG if you configured one, so most calls only need a project_id.

Not implemented

Scoped out deliberately to keep the surface focused and CE-only: file/attachment uploads, pages, estimates, time tracking (worklogs), custom work item types/properties, and the commercial-only epics/initiatives/teamspaces/customers/IDP-sync APIs. These can be added later following the same pattern in src/tools/.

A typical multi-project PM session

1. plane_list_projects — see everything in the workspace.
2. plane_advanced_search_work_items on the active project with a priority/state filter — find what's urgent. It's project-scoped, so call it once per project to cover the whole workspace.
3. plane_list_cycles on the active project, then plane_list_cycle_work_items — check current sprint status.
4. plane_update_work_item — move items between states, reassign, reprioritize.
5. plane_add_work_item_comment — leave status notes.
6. plane_list_intake_issues + plane_update_intake_issue — clear the triage queue.

Development

npm run dev     # tsx watch, runs src/index.ts directly
npm run build   # compile to dist/
npm start       # run compiled dist/index.js

Test with the MCP Inspector:

npx @modelcontextprotocol/inspector node dist/index.js

(Set PLANE_BASE_URL / PLANE_API_KEY / PLANE_WORKSPACE_SLUG in the Inspector's environment panel.)

Notes on endpoint stability

This server was built from Plane's hosted API docs (developers.plane.so) plus the documented self-hosting behavior — self-hosted instances share the same /api/v1 surface, but exact behavior can vary slightly by Plane version. If a less common tool (e.g. plane_advanced_search_work_items filter syntax) returns a 400/404 on your instance, prefer the simpler plane_list_work_items / plane_list_states / plane_list_labels tools and filter client-side, or check your instance's own API docs at <your-plane-url>/api/ if exposed.