Plane MCP Server CE

[!IMPORTANT]

Community Edition and self-hosted first

This fork exists to provide the broadest possible MCP compatibility with the free, self-hosted Plane Community Edition. It is not intended for upstream contribution: its focus is making every capability that CE actually exposes usable by AI agents, while keeping Cloud-only and paid features out of their tool list.

Issues and pull requests that improve Plane CE or self-hosted compatibility are warmly welcome. Contributions authored with AI coding agents are welcome too, provided they are clean, reviewed, and remain aligned with this CE and self-hosted focus.

A Model Context Protocol (MCP) server for Plane integration. This package is published on PyPI as plane-community-mcp and provides tools and resources for interacting with self-hosted Plane CE through AI agents. The distribution name is intentionally different from the executable: install plane-community-mcp, then run plane-mcp-server-ce.

This repository is a fork of plane-mcp-server-ce. It publishes under its own distribution name because the PyPI project plane-mcp-server-ce belongs to the upstream project; the GitHub repository and the CLI command keep the original name so existing agent configurations keep working.

Features

• 🏠 CE-first: hides API surfaces that self-hosted Community Edition cannot serve.
• 🔐 Two credential paths: an API key (PAT) for the public API; a browser session for the CE app-API features (pages, archive).
• 📄 Useful Pages support: CE project pages support create, retrieve, rename, HTML content updates, archive, unarchive, and archived-page deletion.
• 🔌 Two transports: stdio and PAT-header streamable HTTP. OAuth transports were removed — Plane CE has no OAuth provider endpoints (/auth/o/… returns 404), so they could never work self-hosted.

Usage

The server supports two transport methods. We recommend using uvx as it doesn't require installation.

Install name vs. run command

The PyPI distribution is plane-community-mcp, while the executable remains plane-mcp-server-ce. Use both names when starting it with uvx:

uvx --from plane-community-mcp plane-mcp-server-ce --help

Do not use uvx plane-community-mcp: that is the installable distribution, not the executable name. If you prefer a persistent installation instead:

python -m pip install plane-community-mcp
plane-mcp-server-ce stdio

Requirements:

• Python 3.10+ (for stdio transport, via uvx)
• Node.js 22+ (for remote transports, via npx)

1. Stdio transport against self-hosted Plane CE (recommended)

This is the standard setup for a self-hosted Community Edition instance. Set the environment variables before launching the server:

export PLANE_BASE_URL="https://your-plane.example"   # your CE instance origin
export PLANE_API_KEY="your-api-key"                  # created in CE workspace settings → API
export PLANE_WORKSPACE_SLUG="your-workspace"
export PLANE_MCP_EDITION="community"

# Session credentials — required for the CE-only tools this fork exists for
# (project pages, work-item archive/unarchive). Everything else works with
# the API key alone; without these, pages and archive tools stay hidden.
# export PLANE_SESSION_COOKIE="<session-id cookie value>"   # preferred
# … or email + password instead of a cookie:
# export PLANE_SESSION_EMAIL="you@example.com"
# export PLANE_SESSION_PASSWORD="your-password"

uvx --from plane-community-mcp plane-mcp-server-ce stdio

Project pages and work-item archiving are the reason to run this fork instead of upstream — and they require session credentials: without PLANE_SESSION_* those tools stay hidden, while the rest of the server works with the API key alone. See Session-only capabilities for how to obtain the cookie.

MCP Client Configuration (using uvx - recommended):

{
  "mcpServers": {
    "plane": {
      "command": "uvx",
      "args": ["--from", "plane-community-mcp", "plane-mcp-server-ce", "stdio"],
      "env": {
        "PLANE_API_KEY": "<your-api-key>",
        "PLANE_WORKSPACE_SLUG": "<your-workspace-slug>",
        "PLANE_BASE_URL": "https://<your-self-hosted-plane-url>",
        "PLANE_MCP_EDITION": "community",
        "PLANE_SESSION_COOKIE": "<your-session-id-cookie>"
      }
    }
  }
}

The PLANE_SESSION_COOKIE entry (or PLANE_SESSION_EMAIL + PLANE_SESSION_PASSWORD) is what turns on the pages and archive tools — the CE features this fork exists for. Omit it and those tools stay hidden.

2. Self-hosted HTTP transport (PAT headers)

Run the server on your own network when several clients need to reach it over HTTP, or when your client only speaks URL-based transports. The server listens on port 8211 and serves a single endpoint:

The server only needs to know where your Plane instance lives; each client authenticates with its own API key:

export PLANE_BASE_URL="https://your-plane.example"
export PLANE_MCP_EDITION="community"
uvx --from plane-community-mcp plane-mcp-server-ce http

Or with Docker (the image defaults to the http transport):

docker build -t plane-mcp-server-ce .
docker run -p 8211:8211 \
  -e PLANE_BASE_URL="https://your-plane.example" \
  -e PLANE_MCP_EDITION="community" \
  plane-mcp-server-ce

Client configuration (mcp-remote forwards the headers; ${VAR} is expanded from the client's environment):

{
  "mcpServers": {
    "plane": {
      "command": "npx",
      "args": [
        "mcp-remote@latest",
        "http://your-server:8211/http/api-key/mcp",
        "--header", "Authorization: Bearer ${PLANE_API_KEY}",
        "--header", "x-workspace-slug: ${PLANE_WORKSPACE_SLUG}"
      ]
    }
  }
}

The API key must travel in the Authorization: Bearer header — that is the only header the token middleware inspects — and x-workspace-slug names the workspace. To use the session-only tools (pages, archive) over HTTP, also set PLANE_SESSION_* on the server, as in section 1.

About Plane Cloud: this server targets self-hosted CE and authenticates with API keys only. Plane Cloud users should connect to Plane's hosted MCP at https://mcp.plane.so (OAuth or PAT) instead of running this fork.

Configuration

Authentication

The server requires authentication via environment variables:

• PLANE_BASE_URL: Base URL for Plane API (default: https://api.plane.so). For self-hosted CE, set this to your instance origin, e.g. https://your-plane.example.
• PLANE_API_KEY: API key for authentication (required for stdio transport)
• PLANE_WORKSPACE_SLUG: Workspace slug identifier (required for stdio transport)
• PLANE_INTERNAL_BASE_URL: Internal URL preferred over PLANE_BASE_URL for server-to-server calls (useful when the MCP server runs inside the same network as Plane). Also consulted by PLANE_MCP_EDITION=auto when detecting a self-hosted instance.
• PLANE_MCP_EDITION: Tool discovery mode: community (or ce) exposes only tools verified against Plane CE; cloud (or all) exposes the complete SDK surface; auto is the default and treats a configured non-*.plane.so API URL as self-hosted. Set community explicitly for predictable self-hosted deployments, especially if you use a custom Cloud domain.
• PLANE_SESSION_EMAIL / PLANE_SESSION_PASSWORD, or PLANE_SESSION_COOKIE: CE-only app-session credentials — required for the tools this fork exists for (work-item archive/unarchive and project pages); without them those tools are hidden from discovery. See Session-only capabilities.

Example (self-hosted CE, stdio transport):

export PLANE_BASE_URL="https://your-plane.example"
export PLANE_API_KEY="your-api-key"
export PLANE_WORKSPACE_SLUG="your-workspace-slug"
export PLANE_MCP_EDITION="community"

Note: For the self-hosted HTTP transport (section 2), set PLANE_BASE_URL (and PLANE_MCP_EDITION) on the server; each client then authenticates with an Authorization: Bearer <api-key> header plus x-workspace-slug.

Logging

The server emits structured JSON logs. Each tool call is logged with its tool name, duration, status, and workspace slug.

• LOG_LEVEL: Python log level; defaults to INFO. Set to WARNING in a high-volume production deployment or DEBUG while troubleshooting.
• Tool arguments and other request payloads are never logged by default.
• LOG_USER_INFO: When true, include user info (PII such as the display name) in logs alongside the opaque user id. Defaults to false so PII is never logged unless explicitly opted in. Only the PAT (header) HTTP transport carries request-level auth context; stdio is unaffected.

export LOG_USER_INFO="true"

Available Tools

The server provides comprehensive tools for interacting with Plane. All tools use Pydantic models from the Plane SDK for type safety and validation.

Community Edition availability

Set PLANE_MCP_EDITION=community to prevent unavailable tools from being advertised to an agent. This keeps the MCP tool list focused on functionality that exists on the free, self-hosted edition instead of returning cryptic 404 errors. The detailed endpoint evidence is maintained in CE_COMPAT.md.

The category tables below describe the full SDK surface. Rows marked No or Partial above are deliberately omitted from MCP discovery in Community Edition mode. Rows marked Session are hidden by default and exposed only when app-session credentials are set.

Session-only capabilities (Community Edition)

A few things exist on a self-hosted CE instance but are served only by the internal app API (/api/…, no /v1), which uses a browser session and rejects a personal access token with 401: work-item archive/unarchive (and listing archived items) and project pages.

Provide app-session credentials to unlock them. The MCP then logs in like the web app (CSRF + /auth/sign-in/), reuses the session cookie, and routes only these tools through the app API; everything else keeps using your PAT. On Plane Cloud these variables are ignored.

# either email + password …
export PLANE_SESSION_EMAIL="you@example.com"
export PLANE_SESSION_PASSWORD="your-password"
# … or a pre-obtained session cookie (keeps the password out of the environment)
export PLANE_SESSION_COOKIE="<session-id cookie value>"

To get the cookie: log into your CE instance in the browser, then copy the session-id value from DevTools → Application → Cookies. It expires when you log out or the session is invalidated — when the pages and archive tools start returning 401, copy a fresh one. Email + password avoids expiry but places your full account credentials in the environment; prefer the cookie.

Pages available with a session are deliberately small and predictable:

Notes:

• These credentials are your full user login (the app API is more privileged than a scoped PAT). Prefer PLANE_SESSION_COOKIE where possible.
• Only project pages are available; workspace-level pages and work-item↔page links have no CE endpoint and stay hidden.
• Page writes are conservative: they are never automatically replayed. A 4xx means the request was rejected; a 5xx or transport failure may be ambiguous, so retrieve the page before retrying.
• These four mutations are CE-only and intentionally do not appear in Cloud discovery: update_page, update_page_content, archive_page, and unarchive_page. Cloud retains delete_page through the SDK.
• Without these variables, the affected tools stay hidden in CE mode (no cryptic 404s). The endpoint evidence is in CE_COMPAT.md.

Projects

Work Items

Cycles

Modules

Initiatives

Intake Work Items

Work Item Properties

Milestones

Labels

States

Work Item Comments

Work Item Links

Work Item Types

Work Item Relations

Work Item Relation Definitions

Work Item Activities

Work Logs

Pages

Workspaces

Users

Total Tools: 100+ tools across 20 categories

Development

Running Tests

pytest

Code Formatting

black plane_mcp/
ruff check plane_mcp/

License

MIT License - see LICENSE for details.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Deprecation Notice

⚠️ The Node.js-based plane-mcp-server is deprecated and no longer maintained.

This repository represents the new Python+FastMCP based implementation of the Plane MCP server. If you were using the previous Node.js version, please migrate to this Python-based version for continued support and updates.

The new implementation offers:

• Better type safety with Pydantic models
• Improved performance with FastMCP
• Enhanced tool coverage
• Active maintenance and development

For migration assistance, please refer to the configuration examples in this README or open an issue for support.

Old Node.js Configuration (Deprecated):

If you were using the previous Node.js-based @makeplane/plane-mcp-server, your configuration looked like this:

{
  "mcpServers": {
    "plane": {
      "command": "npx",
      "args": [
        "-y",
        "@makeplane/plane-mcp-server"
      ],
      "env": {
        "PLANE_API_KEY": "<YOUR_API_KEY>",
        "PLANE_API_HOST_URL": "<HOST_URL_FOR_SELF_HOSTED>",
        "PLANE_WORKSPACE_SLUG": "<YOUR_WORKSPACE_SLUG>"
      }
    }
  }
}

Please migrate to the new Python-based configuration shown in the Usage section above.

Releasing plane-community-mcp

Maintainers should follow RELEASING.md. The PyPI distribution is plane-community-mcp; the executable remains plane-mcp-server-ce. Publishing uses PyPI Trusted Publishing, so no PyPI token is stored in this repository.