How to connect Plane to Claude Code

A terminal with the claude mcp add command for Plane's MCP server, connected to a Plane project, with the local server for a self-hosted Plane beside it.

CRUX team · · Commands checked on · 5 min read

Plane publishes an official MCP server, and one command adds it to Claude Code: claude mcp add --transport http plane https://mcp.plane.so/http/mcp. After that you run /mcp in a session and sign in to Plane in the browser. For a self-hosted Plane you run the same server on your machine with uvx plane-mcp-server stdio and a personal access token.

The commands come from Plane's developer docs and the makeplane/plane-mcp-server repository.

How do I connect Plane Cloud to Claude Code?

You need Claude Code and a Member or Admin role in the Plane workspace you want to reach. The server is open source under the MIT license. The Plane features it reaches follow your Plane plan and your role.

With a browser sign-in. This is the shortest way for one developer.

claude mcp add --transport http plane https://mcp.plane.so/http/mcp

Start Claude Code and run /mcp to authenticate, or run claude mcp login plane. Plane opens in the browser, you sign in and choose a workspace. The connection stays bound to that workspace, so you reconnect to switch.

To share the server with your team, --scope project writes it to a .mcp.json file in the project root. The entry in Claude Code's format needs "type": "http"; without it Claude Code treats the entry as a local command:

{
  "mcpServers": {
    "plane": {
      "type": "http",
      "url": "https://mcp.plane.so/http/mcp"
    }
  }
}

With a personal access token. Plane's docs suggest this for automations, CI and agents without a browser. Create the token in Plane under Profile Settings, in Personal Access Tokens. The workspace slug is the segment after app.plane.so/ in your Plane address. Keep the token out of a .mcp.json file that you commit.

claude mcp add --transport http plane https://mcp.plane.so/http/api-key/mcp \
  --header "Authorization: Bearer <PAT>" \
  --header "x-workspace-slug: <workspace-slug>"

How do I connect a self-hosted Plane to Claude Code?

The hosted server at mcp.plane.so reaches only Plane Cloud, and the browser sign-in is not available on Plane Community Edition. Run the server locally instead. Local mode needs Python 3.10 or newer and uv.

claude mcp add --transport stdio plane \
  --env PLANE_API_KEY=<your-api-key> \
  --env PLANE_WORKSPACE_SLUG=<your-workspace-slug> \
  --env PLANE_BASE_URL=https://plane.yourcompany.com \
  -- uvx plane-mcp-server stdio

Put your instance address in PLANE_BASE_URL; without it the server calls https://api.plane.so, so your key would go to Plane Cloud. Plane's docs list the variable but print no command with it; this one adds it as one more --env.

Before you add the server, test the token against your Plane's REST API. A 200 response confirms the key and the address.

read -rs PLANE_API_KEY   # paste the key and press Enter; nothing is echoed
curl -H "x-api-key: $PLANE_API_KEY" \
  "https://plane.yourcompany.com/api/v1/users/me/"

How do I check that the connection works?

List the servers Claude Code knows:

claude mcp list

Then ask in a session, for example "List the tasks assigned to me in Plane". If the server does not respond, start Claude Code with the debug flag:

claude --debug

A 401 with the browser sign-in means the token expired, so run /mcp again. A 401 with a personal access token means the token is wrong or revoked. A 403 means your Plane role is too low for the action.

What can Claude Code do in Plane after that, and what can it not do?

The server has 30 tools that cover 207 actions. Plane calls a task a work item. Claude Code can:

  • create, update, search and count tasks, and write PQL filters for them
  • add comments, links, relations, attachments and logged time
  • read and change states, labels, cycles, modules and pages
  • manage task types, custom properties and estimates

The limits come from the same docs:

  • The server acts as the signed-in user, and Plane enforces workspace and project roles. A Guest cannot do more through MCP.
  • A browser sign-in is bound to one workspace.
  • There is no read-only endpoint. Use the tool allow-list in Claude Code.
  • There are no separate tools for epics. An epic is a task of the type "Epic".
  • An action outside your Plane plan returns a message that names the missing feature.

What changes when three or more people do this?

The connection keeps working. The server knows nothing about the team's process.

Ryan's agent moves a task to "In review". Megan does not know whether she starts the review or waits for Ryan to ask, because no state has an owner.

Ryan keeps his prompts in his own notes and Megan keeps hers, so the same kind of task gets a plan from one agent and none from the other.

Emily answers the agent's question about an edge case in a chat thread. A week later Megan tests the task and cannot find that answer.

Three sessions run on three laptops. Nobody sees that one of them has waited since morning for Emily's approval.

How does CRUX handle the team part?

We build CRUX, so this part is about our own product, and it is in beta.

What the agent needs to know about the project is already in Plane: the task, its parent and the decisions already on it. CRUX lets the agent read that, and each status in your workflow has its own instructions, so nobody writes a prompt. CRUX is the workflow layer between a team's tracker and the coding agents the team already uses.

  • Each member pastes their own Plane personal access token into CRUX. They create it at <your Plane web address>/settings/profile/api-tokens/.
  • Self-hosted Plane Community Edition works when it has a public address.
  • Each Plane state that the workflow covers has an owner role.
  • A person starts each step and approves the result at approval checkpoints.
  • Each step posts its artifact as a comment on the task, so answers stay with the task.

When is the plain MCP server enough?

  • You work alone, or one person runs all the agent work.
  • You want to query and update Plane in plain language and need no shared process.
  • Your team already agrees on who starts and approves each step, and that works.
  • Your Plane has no public address. Plane's local mode reaches it, and CRUX does not.

FAQ

Does Plane have an official MCP server?

Yes. Plane maintains it at github.com/makeplane/plane-mcp-server under the MIT license and hosts it at https://mcp.plane.so/http/mcp.

Does the Plane MCP server work with self-hosted Plane?

Yes. Run it locally with PLANE_BASE_URL set to your instance, or deploy your own copy of the server.

Do I need CRUX to connect Plane to Claude Code?

No. The commands above are all one developer needs.

Try this on your own project. CRUX is free for one person, no card.

Start free

Next: How to connect GitHub Issues to Claude Code

All articles