CloudShift Plane MCP

A Model Context Protocol server for Plane that works with self-hosted Plane Community Edition, connects with a plain API key over HTTP, and adds deterministic team reports (daily standup, per-person, project, module, cycle, workspace).

It's built on the official makeplane/plane-mcp-server (MIT), with all 177 upstream tools kept, plus:

• Plane CE support. A read adapter that uses the /issues/ API paths older Community Edition builds expose, plus retry and backoff for the 429/502/503 responses common behind self-hosted reverse proxies.

• API-key-only HTTP mode. Run remote HTTP without configuring a Plane OAuth app (PLANE_MCP_DISABLE_OAUTH=true). Clients authenticate with Authorization: Bearer <key> or x-api-key.

• URL-scoped workspaces. /http/api-key/w/<workspace>/mcp lets clients that can't send custom headers (such as Claude.ai custom connectors) pick a workspace from the URL.

• Team reports. Seven cloudshift_plane_* tools compute progress, blocked, overdue, due-soon, stale, and unassigned counts in code, not by the LLM, so numbers are reproducible.

Not affiliated with or endorsed by Plane Software, Inc. "Plane" is a trademark of its owner.

Contents

• Quick start

• Connect a client

• Configuration

• Tools

• Deployment

• Development

• Documentation

• License and credits

Related MCP server: plane-mcp

Quick start

Requirements: Python 3.10+ and uv. You need a Plane workspace API token (Plane → Workspace settings → API tokens).

git clone https://github.com/Sabariramamoorthy/cloudshift-plane-mcp.git
cd cloudshift-plane-mcp
uv sync
cp .env.example .env   # then fill in PLANE_BASE_URL, PLANE_API_KEY, PLANE_WORKSPACE_SLUG

Run it locally over stdio (for Cursor, Claude Desktop, VS Code):

set -a; . ./.env; set +a
uv run plane-mcp-server stdio

Or as an HTTP server on port 8211:

set -a; . ./.env; set +a
uv run plane-mcp-server http

Check that it answers (an MCP initialize should return HTTP 200):

curl -s -o /dev/null -w "%{http_code}\n" -X POST http://127.0.0.1:8211/http/api-key/mcp \
  -H "Authorization: Bearer $PLANE_API_KEY" \
  -H "x-workspace-slug: $PLANE_WORKSPACE_SLUG" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"curl","version":"0"}}}'

Connect a client

Local (stdio), the simplest option for a single user:

{
  "mcpServers": {
    "plane": {
      "command": "uv",
      "args": ["--directory", "/path/to/cloudshift-plane-mcp", "run", "plane-mcp-server", "stdio"],
      "env": {
        "PLANE_BASE_URL": "https://plane.example.com",
        "PLANE_API_KEY": "<your-api-key>",
        "PLANE_WORKSPACE_SLUG": "<your-workspace>"
      }
    }
  }
}

Remote (HTTP), for clients that support headers, such as Cursor:

{
  "mcpServers": {
    "plane": {
      "url": "https://mcp.example.com/http/api-key/mcp",
      "headers": {
        "Authorization": "Bearer <your-api-key>",
        "x-workspace-slug": "<your-workspace>"
      }
    }
  }
}

For Claude Desktop, Claude.ai custom connectors, and VS Code, see docs/clients.md.

Configuration

All settings are environment variables. .env.example is a commented template. The essentials:

The full reference, including OAuth, Redis, and report tuning, is in docs/configuration.md.

Tools

184 tools in total:

Full list: docs/tools.md. Report details and output format: docs/reports.md.

On self-hosted Community Edition, some upstream tools return 404 because the endpoint is Commercial-only or older CE builds lack it. Pages are the most common case. See docs/self-hosted-ce.md for what to expect and which tools to use instead.

Deployment

Step-by-step instructions, including security guidance for public exposure, are in docs/deployment.md.

Development

uv sync --extra dev
uv run pytest                        # unit tests; live tests skip without credentials
uv run ruff check .
uv run ruff format .

Integration tests against a real Plane instance: copy .env.test to .env.test.local, fill it in, and run pytest tests/test_integration.py. Layout and request flow are covered in docs/architecture.md. Contributions are welcome; see CONTRIBUTING.md.

Documentation

License and credits

MIT. Based on makeplane/plane-mcp-server by the Plane MCP Server contributors; their copyright notice is retained. CloudShift additions live mainly in cloudshift/, plane_mcp/claude_workspace.py, and the header auth provider.