Plane MCP Server: The Complete Guide (2026)

TL;DR: which Plane MCP should you use

The decision collapses to two questions: do you want a hosted endpoint with browser OAuth, and do you run Plane Cloud or a self-hosted instance?

• Most people, and anyone who wants zero install: use the official server, makeplane/plane-mcp-server (Python, MIT). Plane hosts it at https://mcp.plane.so/http/mcp — point a remote-MCP client at that URL, approve the OAuth consent screen, done. It is the actively developed implementation and covers Plane’s full API surface — north of 100 tools. Its catalog page is /servers/plane-project-management.
• You want a Node-native local server on Plane Cloud, no Python, no OAuth: use the community server, @disrex/plane-mcp-server (TypeScript, MIT). It runs via npx with an API key and workspace slug, adds cursor-based pagination, and is the entry behind our /servers/plane install card below. One hard limit: it is Cloud-only and will not talk to a self-hosted Plane.
• You have not picked a PM tool yet: read our Jira vs Linear vs Trello vs Productboard MCP comparison before installing anything — Plane is the open-source option in that field.

The copy-paste, if that’s all you came for:

# Official server, hosted + OAuth (Claude Code)
claude mcp add --transport http plane https://mcp.plane.so/http/mcp
# then run /mcp inside Claude Code to complete the OAuth flow

# Official server, local via uvx (Python 3.10+)
#   env: PLANE_API_KEY, PLANE_WORKSPACE_SLUG
uvx plane-mcp-server stdio

One naming note before you scroll: Plane renamed issues to work items. The official server uses the new vocabulary (create_work_item); the community server still says issue. They are the same object.

The Plane MCP landscape (why there are two)

Search any directory for “plane” and you get a handful of near-identical servers. They sort into three tiers, and knowing the history saves you from installing the wrong one.

The history: Plane shipped its first MCP server as a Node.js package, then rewrote it in Python on FastMCP for “improved type safety and performance,” per the repo. The README is explicit that “the Node.js-based plane-mcp-server is deprecated and no longer maintained”. The @disrex community server is a separate lineage — an enhanced fork of the earlier kelvin6365/plane-mcp-server — and it stayed on TypeScript. So the two live options today are the official Python server and the community Node fork; the original official Node build is a dead end.

Plane’s own trajectory explains why any of this exists. The company has leaned hard into AI, on both sides of the protocol — an MCP server so agents can drive Plane, and MCP connectors inside Plane AI so Plane can reach out to other tools:

The install card above is the community server (our /servers/plane entry). The official server’s canonical page is /servers/plane-project-management. For the wider picture of PM tooling on MCP, our Jira MCP guide walks the same official-vs-community split for Atlassian.

Our take: default to the official server. It is where development happens, it hosts a remote endpoint so most clients need no install, and it is the only one that reaches a self-hosted instance. Run the community fork when you specifically want a Node-only, Cloud-only, no-OAuth setup.

What Plane is (for searchers who found Plane first)

Plane is an open-source project-management platform — the GitHub description calls it an “open-source Jira, Linear, Monday, and ClickUp alternative”. It was built by brothers Vamsi and Vihar Kurama and is developed in the open at github.com/makeplane/plane, one of the fastest-rising project-management repos on GitHub. It reached the top project-management spot on GitHub in under a year, a milestone its Hacker News thread documented.

The core objects map cleanly onto the MCP tools you will call: work items (issues) live in projects; cycles are time-boxed sprints; modules group work like epics; initiatives and milestones track larger goals across projects; and intake is the triage inbox for un-sorted requests. If you know Linear or Jira, the vocabulary transfers with minor renames.

The pitch is data ownership without the platform tax: Plane runs on your own infrastructure via Docker or Kubernetes, supports air-gapped deployments, and is free to self-host. The platform is AGPL-licensed (the MCP servers are MIT), which one Hacker News commenter praised because it means Plane “cannot be ever closed source.” That control is why teams reach for an MCP server — they already run the instance; the server lets an agent operate it.

Auth & hosting: the real difference

Auth is where the two servers genuinely diverge — more than tools, more than features. Pick based on where your credentials should live and where Plane runs.

Getting a token

Both servers authenticate with a Plane token. Generate one in the Plane UI: Profile Settings → API Tokens for a personal token, or Workspace Settings → Access Tokens for a workspace-scoped one. Name it, create it, and copy the value immediately — Plane displays it once. You also need your workspace slug, the segment in app.plane.so/your-workspace-slug.

Official server: hosted OAuth, PAT, or local stdio

The official server gives you three front doors, per its README:

• Hosted OAuth — point a client at https://mcp.plane.so/http/mcp. A browser consent flow issues a token bound to your Plane identity; nothing is stored in a config file. This is the right default for a human at a keyboard.
• Hosted PAT — for headless use, call https://mcp.plane.so/http/api-key/mcp with Authorization: Bearer <token> and an X-Workspace-slug header. No browser in the loop, so it suits bots and CI.
• Local stdio — run uvx plane-mcp-server stdio with PLANE_API_KEY, PLANE_WORKSPACE_SLUG, and optionally PLANE_BASE_URL. This is the path for self-hosted Plane and for keeping traffic on your own machine.

Two self-hosting knobs matter: PLANE_BASE_URL points at your instance (default https://api.plane.so), and PLANE_INTERNAL_BASE_URL handles server-to-server calls inside your network. For the OAuth transports, the server validates each client’s redirect URI against an allowlist; if you use a client it does not recognize, add a pattern via PLANE_OAUTH_ALLOWED_REDIRECT_URIS rather than forking.

Community server: env vars, Cloud only

The community server keeps it simple: PLANE_API_KEY plus PLANE_WORKSPACE_SLUG in the client’s env block, and it always talks to app.plane.so. There is no base-URL override — its README warns it is “designed specifically for Plane Cloud instances” and will not work with a self-hosted install.

Here is the counter-intuitive part. We expected the community fork to be the self-host-friendly one — that is usually how it goes. It is the opposite: the official server is the one that reaches your own instance, and the community server is locked to Cloud. If you self-host Plane, the official server is not just the better choice, it is the only choice.

Install (every client)

Start with the official server. For clients that speak remote MCP natively — Claude, Cursor, VS Code, Windsurf, Zed, all documented by Plane — paste the hosted URL and let OAuth handle the rest:

# Claude Code — hosted official server, OAuth
claude mcp add --transport http plane https://mcp.plane.so/http/mcp
# run /mcp inside a session to approve access

For a local install of the official server, register the stdio command. The README recommends uvx (no install step); Python 3.10+ is the only prerequisite:

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

Self-hosted Plane users: change PLANE_BASE_URL to your instance. Clients without native remote-MCP support can still reach the hosted endpoint through the mcp-remote bridge (npx mcp-remote@latest https://mcp.plane.so/http/mcp), which needs Node.js 22+. Full per-client flags and config-file paths live at /clients/claude-code and the other pages under mcp.directory/clients.

Community server setup (@disrex/plane-mcp-server)

The community server is a stdio process your client launches via npx. The install panel below pulls its config from our canonical /servers/plane entry, so it stays in sync with the package name and env-var shape. Pick your client, copy, paste, fill in the API key and workspace slug, restart.

One-line install · Plane

Open server page

Install

Cursor

One-click install

VS Code

One-click install

Claude Desktop

Copy configuration

Claude Code

Copy CLI command

CLI

Gemini

Copy CLI command

CLI

Codex

Copy CLI command

CLI

Windsurf

Copy configuration

ChatGPT

Add via Settings → Connectors

M

Manual

Copy configuration

The manual JSON, for reference — note it needs Node.js 22+ and works only against Plane Cloud:

{
  "mcpServers": {
    "plane": {
      "command": "npx",
      "args": ["-y", "@disrex/plane-mcp-server"],
      "env": {
        "PLANE_API_KEY": "your_plane_api_key_here",
        "PLANE_WORKSPACE_SLUG": "your_workspace_slug_here"
      }
    }
  }
}

One gotcha the README flags: generate the key from your personal settings, not workspace settings, for this server. Browse other hosted options like the official endpoint at /remote-mcp-servers.

Tools walkthrough

The two servers cover the same Plane concepts under different names and at different breadth. Knowing the exact tool names helps when you write agent prompts or allowlists.

Official server — work-item vocabulary, full surface

The official server exposes north of 100 tools across 20-plus resource types, all built on Pydantic models from the Plane SDK for validation. The groups you will use most:

• Projects: list_projects, create_project, retrieve_project, update_project, get_project_members, get_project_worklog_summary.
• Work items: list_work_items, create_work_item, retrieve_work_item, retrieve_work_item_by_identifier, update_work_item, search_work_items — the search tool is the workhorse for “find me…” prompts.
• Cycles & modules: create_cycle, manage_cycle_work_items, transfer_cycle_work_items, manage_cycle_archive, and the mirrored *_module_* set for epic-style grouping.
• Planning & the rest: initiatives, milestones, intake (triage), work-item properties, labels, states, comments, links, relations, work-item types, activities, work logs (time tracking), pages, workspaces, and users each get their own list/create/update/delete tools.

Community server — issue vocabulary, ~76 tools

The community server ships roughly 76 tools using Plane’s older issue vocabulary: create and list issues, states, modules (sprints), cycles, labels, comments, links, attachments, worklogs, issue types, intake, sub-issues, and issue transfer between cycles. Its standout is cursor-based pagination on every list operation, with configurable page sizes up to 100 — useful for walking a large workspace without blowing the context window.

Takeaway: for everyday work — create, update, search, plan a cycle — the two are at parity. The official server wins on breadth (initiatives, milestones, pages, custom properties) and on being current with Plane’s API; the community server wins on a small Node footprint. Choose on hosting and auth, not on the tool list.

Recipes

Four workflows that justify the install. Tool names below use the official server; the community equivalents swap work item for issue.

Recipe 1 — Plan the next cycle from a backlog

Prompt: “Look at open work items in the Web project, group them by priority and assignee, and propose a two-week cycle that fits our usual velocity. Create the cycle and add the items you picked.” The agent calls list_work_items, reasons over the set, then create_cycle and manage_cycle_work_items. Plane’s own team pitches exactly this on X — “Ask Plane AI to break work down by assignee, priority, state” — and the MCP server is what lets any agent, not just Plane AI, do it.

Recipe 2 — File a work item from a spec or bug report

Paste a spec paragraph or a stack trace and prompt: “Create a work item in Web for this. Write a clear title, put repro steps in the description, set priority, and label it bug. Check for duplicates first.” The duplicate check is one search_work_items call; the filing is create_work_item. An agent writes better repro steps than most humans do at 5 p.m. — it has the whole trace in context and no incentive to skip fields.

Recipe 3 — Standup digest

Prompt: “Summarize what changed in the Web project in the last 24 hours — items that moved state, new bugs, and anything closed. Three bullets per section, mention assignees.” The agent leans on list_work_items with filters and the activities tools for the change history, then formats the digest. Teams pipe this into Slack via a second MCP server, or write it to a Plane page with the page tools.

Recipe 4 — Roll up an initiative

Prompt: “For the Q3 Billing initiative, list every linked project and its open vs done work-item counts, and flag any module with no activity this cycle.” This is the recipe the official server enables and the community one does not — initiatives and milestones are official-only tools. It chains list_initiatives, list_work_items per project, and the module tools into a status rollup that would otherwise be a manual afternoon.

Limits worth knowing before you commit

• Self-hosted version drift is the sharpest edge. Several open issues on the official repo report 404s against older Community Edition instances — the SDK calls /work-items/ or a projects-lite endpoint that an older self-hosted build exposes at a different path (or under /issues/). The fix is almost always update the instance; the server tracks Cloud’s current API, and old CE lags it.
• Permissions are a floor and a ceiling. The token only sees projects it belongs to. A reported gotcha: a workspace admin who is not a member of a project gets a 404 for it, which reads like a bug but is the permission model. Add the agent’s account to the projects it should touch.
• Community server is Cloud-only. Full stop — no PLANE_BASE_URL, no self-hosted reach. That is what the official server is for.
• Two runtimes. The official server wants Python 3.10+ for stdio (via uvx) and Node 22+ only for the mcp-remote bridge; the community server wants Node 22+. Mismatched runtimes are a common “server won’t start” cause.
• Cost: both servers are free and MIT. You pay for Plane itself — nothing if you self-host, a per-seat subscription on Cloud. The practical constraint is your Plane plan, not the MCP layer.

Troubleshooting

What the community says

Plane earns real enthusiasm and real skepticism, and both matter before you standardize on it. Its Hacker News launches drew hundreds of points, and the recurring theme is self-hosting as the whole point — the appeal, one commenter wrote, is “that you can self-host it at all, which JIRA now discontinued unless you pay” a large annual fee. Co-founder Vihar Kurama shows up in those threads, and on X the team frames Plane AI around “assigning work items to coding agents” — the exact workflow this MCP server unlocks.

The contrarian case is sharper. The strongest version, from a Hacker News commenter, is that self-hosting a PM tool rarely pencils out: “Jira licensing costs are on the order of about 10 minutes of employee time per month. So, if it is even slightly worse it’s a financial disaster.” Others question originality — one called Plane “a total rip-off of Linear.app” — and maturity, calling it “about 1/500th of the features” of Jira. Even Plane’s own blog concedes that teams self-hosting purely to cut costs are often better off on Cloud. The MCP server does not change that math: if a hosted PM tool already fits, adding an agent to your own instance is not a reason to switch.

The Verdict

Frequently Asked Questions

Sources

• Official server (Python, transports, tool tables, deprecation note): github.com/makeplane/plane-mcp-server
• Official MCP docs (hosted endpoints, token creation, supported clients, self-hosting): developers.plane.so/dev-tools/mcp-server
• Community server (Cloud-only, issue vocabulary, cursor pagination, fork lineage): github.com/disrex-group/plane-mcp-server
• Real user issues (self-hosted 404s, empty search, OAuth redirect, permissions): makeplane/plane-mcp-server/issues
• Plane platform (Jira/Linear alternative, AGPL, self-host): github.com/makeplane/plane
• Community sentiment & contrarian voices: HN — “Plane: Open-Source Alternative to Jira” · HN — “top spot in project management”
• First-party X post (MCP connectors + agents in Plane AI): @planepowers, May 15, 2026
• Canonical MCP.Directory entries: /servers/plane · /servers/plane-project-management