Plane MCP Server

A Model Context Protocol server for Plane. Gives an AI agent tools to read and manage projects, work items, cycles, modules, releases, customers and more.

Built on FastMCP and the official plane-sdk.

• 30 tools, one per Plane resource, covering 204 operations
• Local or remote — stdio, streamable HTTP, SSE
• OAuth or API key authentication

Quick start

Get an API key from Plane: Workspace Settings → API tokens.

Add this to your MCP client's configuration:

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

uvx needs no install step. Requires Python 3.10+.

For a self-hosted Plane, add "PLANE_BASE_URL": "https://plane.example.com".

Transports

stdio — local

Runs as a subprocess of your MCP client. Configuration as shown above; needs PLANE_API_KEY and PLANE_WORKSPACE_SLUG.

PLANE_API_KEY=... PLANE_WORKSPACE_SLUG=... uvx plane-mcp-server stdio

HTTP with OAuth — hosted

https://mcp.plane.so/http/mcp

The OAuth flow is handled on connect; no credentials in your config. For clients without native remote MCP support, bridge with mcp-remote:

{
  "mcpServers": {
    "plane": {
      "command": "npx",
      "args": ["mcp-remote@latest", "https://mcp.plane.so/http/mcp"]
    }
  }
}

Requires Node.js 22+.

HTTP with a personal access token — hosted

https://mcp.plane.so/http/api-key/mcp

{
  "mcpServers": {
    "plane": {
      "command": "npx",
      "args": ["mcp-remote@latest", "https://mcp.plane.so/http/api-key/mcp"],
      "headers": {
        "Authorization": "Bearer <PAT>",
        "X-Workspace-slug": "<workspace-slug>"
      }
    }
  }
}

SSE — deprecated

https://mcp.plane.so/sse is maintained for backward compatibility only. Use an HTTP transport instead.

Tools

The server advertises 30 tools, one per resource. Each takes an action parameter that selects the operation:

workitem(action="create", project_id=..., name="Fix login")
workitem(action="list", project_id=..., pql='state__group = "started"')
cycle(action="archive", project_id=..., cycle_id=...)

Every tool's description lists its actions with their required and optional parameters, so the catalogue is self-documenting at call time.

→ Full tool and action reference

Querying work items

List, count and search accept PQL, Plane's query language:

workitem(action="list", project_id=..., pql='state__group = "started" AND priority = "urgent"')
workitem(action="count", pql='assignees__id = "<member id>"', group_by="state_id")

Call get_pql_reference for the full syntax, operators and worked examples.

Upgrading from the per-operation tools

Earlier releases exposed one tool per API operation. Existing integrations keep working: 169 of those 177 names still resolve to the consolidated tool, so a saved prompt or script calling create_work_item or list_cycles needs no change. They are no longer advertised, and they keep the parameter names they shipped with (work_item_id, not workitem_id).

Seven names chose between two operations with a parameter (manage_project_archive(archive=False)), which one tool-and-action pair cannot reproduce; calling one tells you its replacement. get_pql_reference is unchanged.

Configuration

Authentication

The remote transports carry credentials in the connection — the OAuth flow or the PAT headers — and need none of these.

Self-hosting the server itself:

OAuth redirect URIs

The OAuth transports validate each client's redirect URI against an allowlist. Common clients (Cursor, VS Code, Claude.ai, ChatGPT connectors, localhost) are allowed by default.

To onboard a new client without a release, append patterns:

export PLANE_OAUTH_ALLOWED_REDIRECT_URIS="https://newclient.com/cb,https://other.app/oauth/*"

* matches any port, path segment or subdomain. Keep the host pinned and wildcard only the port or path.

Logging

Structured JSON. Each tool call logs its name, duration, status and — when available — an opaque user id and the workspace slug.

export LOG_USER_INFO=false    # also log the display name (PII);
export LOG_PAYLOADS=false    # keep request payloads out of logs; default true

Only the OAuth and PAT transports carry a display name; stdio is unaffected.

Development

git clone https://github.com/makeplane/plane-mcp-server
cd plane-mcp-server
uv pip install -e ".[dev]"

Run the server against a workspace:

PLANE_API_KEY=... PLANE_WORKSPACE_SLUG=... python -m plane_mcp stdio
python -m plane_mcp http            # port 8211

Tests, format, lint:

pytest                              # no network or credentials needed
ruff format plane_mcp/ tests/       # line length 120
ruff check plane_mcp/ tests/        # rules E, F, I, UP, B

The suite runs fully offline — every action of every resource is executed against a stand-in that binds each call against the genuine plane-sdk signature. See plane_mcp/tools/README.md.

Live integration tests are skipped unless you point them at a running server:

export PLANE_TEST_API_KEY=... PLANE_TEST_WORKSPACE_SLUG=...
export PLANE_TEST_MCP_URL=http://localhost:8211    # optional; this is the default
pytest tests/test_integration.py -v

They write real data to that workspace.

Repository layout

Contributing

Pull requests welcome. Please run pytest and ruff check before submitting; new tools should come with the invariants described in plane_mcp/tools/README.md.

See CONTRIBUTING.md and CODE_OF_CONDUCT.md.

Migrating from the Node.js server

@makeplane/plane-mcp-server (Node.js) is deprecated and unmaintained. This Python implementation replaces it.

Replace the command and args with the stdio configuration in Quick start.

License

MIT — see LICENSE.