plane-mcp

Local MCP server for a self-hosted Plane instance. Exposes tickets (work items), cycles, modules, labels, and states as MCP tools, plus a small set of mutation tools (label add/remove, state changes, ticket create/update, module attach).

The Plane API key is read only from the PLANE_API_KEY environment variable. It is never logged, never printed, and never included in tool output — errors are redacted before being returned.

Setup

npm install
npm run build

export PLANE_BASE_URL="https://your-plane-instance.example.com"
export PLANE_API_KEY="..."
export PLANE_DEFAULT_WORKSPACE="..."          # optional
export PLANE_DEFAULT_PROJECT_ID="..."         # optional
export PLANE_DEFAULT_PROJECT_IDENTIFIER="..." # optional
export PLANE_ENABLE_WRITES="false"            # optional; must be true for mutations

Copy .env.example to .env for reference (placeholders only — never commit a real .env).

Run

npm start
# or during development:
npm run dev

The server speaks MCP over stdio.

MCP client config (stdio)

{
  "mcpServers": {
    "plane": {
      "command": "node",
      "args": ["/absolute/path/to/plane-mcp/dist/src/index.js"],
      "env": {
        "PLANE_BASE_URL": "https://your-plane-instance.example.com",
        "PLANE_API_KEY": "${PLANE_API_KEY}",
        "PLANE_DEFAULT_WORKSPACE": "${PLANE_DEFAULT_WORKSPACE}",
        "PLANE_DEFAULT_PROJECT_ID": "${PLANE_DEFAULT_PROJECT_ID}",
        "PLANE_ENABLE_WRITES": "false"
      }
    }
  }
}

Exposed tools

Tools return normalized, allowlisted summaries rather than raw Plane API records. Mutating tools accept dry_run: boolean for previews. Real writes are disabled unless PLANE_ENABLE_WRITES=true is set, and each mutating call must also pass confirm: true; successful ticket updates are verified by re-fetching the record afterward, while comment creation returns the created comment from Plane.

plane_add_comment accepts either comment_text or comment_html. comment_text is escaped and converted to simple paragraph HTML before it is sent to Plane. Comments default to access: "INTERNAL" unless supplied.

Testing

npm test

Unit tests mock fetch — no real Plane API key is required. Coverage includes: auth header presence without leaking the key, redaction of secrets from errors and result payloads, safe path construction, bounded cursor pagination, schema limits, ticket-key normalization, and label-union (non-clobbering) behavior.

Smoke test

With real credentials exported (see Setup), you can drive the server directly with the MCP inspector, or manually via any MCP-compatible client pointed at node dist/src/index.js. A minimal manual check:

node --input-type=module -e "
import { PlaneClient } from './dist/src/planeClient.js';
const client = new PlaneClient({
  baseUrl: process.env.PLANE_BASE_URL,
  apiKey: process.env.PLANE_API_KEY,
  defaultWorkspace: process.env.PLANE_DEFAULT_WORKSPACE,
});
console.log(await client.paginate('/api/v1/workspaces/'));
"

Known quirks (self-hosted Plane)

• GET /api/v1/workspaces/ may 404 (no cross-workspace listing endpoint on some self-hosted deployments). Set PLANE_DEFAULT_WORKSPACE and use workspace-scoped tools directly instead of relying on plane_list_workspaces.

• Advanced search may return no results when project_id is included; the client retries workspace-wide and filters client-side.

• Cycle-issue and module-issue list endpoints may return link objects ({ issue: <uuid> }) rather than full ticket records. Current-cycle tools keep link summaries by default; pass include_full_tickets: true to join normalized ticket summaries.

Security

• Credentials are read only from environment variables (PLANE_API_KEY, PLANE_BASE_URL).

• The API key is never printed, logged, or embedded in responses.

• Errors (HTTP failures, network failures, JSON parse failures) are passed through a redactor before being surfaced to the MCP client.

• Tool arguments used in Plane URL paths are validated and encoded before request construction.

• Tool outputs are allowlisted and redacted; raw Plane API records are not returned to MCP clients.

• Writes are off by default and require both PLANE_ENABLE_WRITES=true and confirm: true on each mutating call.

• .env is gitignored; only .env.example with placeholders is committed.