Plane

Plane MCP Server

Ein Model Context Protocol-Server für Plane. Gibt einem KI-Agenten Werkzeuge zum Lesen und Verwalten von Projekten, Arbeitselementen, Zyklen, Modulen, Releases, Kunden und mehr.

Basiert auf FastMCP und dem offiziellen plane-sdk.

• 28 Werkzeuge, eines pro Plane-Ressource, die 183 Operationen abdecken
• Lokal oder remote — stdio, streamable HTTP, SSE
• OAuth- oder API-Key-Authentifizierung

Schnellstart

Holen Sie einen API-Key von Plane: Workspace Settings → API tokens.

Fügen Sie dies zur Konfiguration Ihres MCP-Clients hinzu:

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

uvx benötigt keinen Installationsschritt. Erfordert Python 3.10+.

Für ein selbst gehostetes Plane fügen Sie "PLANE_BASE_URL": "https://plane.example.com" hinzu.

Transporte

stdio — lokal

Läuft als Unterprozess Ihres MCP-Clients. Konfiguration wie oben gezeigt; benötigt PLANE_API_KEY und PLANE_WORKSPACE_SLUG.

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

HTTP mit OAuth — gehostet

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

Der OAuth-Ablauf wird beim Verbinden abgewickelt; keine Anmeldedaten in Ihrer Konfiguration. Für Clients ohne native Remote-MCP-Unterstützung überbrücken Sie mit mcp-remote:

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

Erfordert Node.js 22+.

HTTP mit persönlichem Zugriffstoken — gehostet

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

Header	Wert
Authorization	Bearer <PAT>
X-Workspace-slug	<workspace-slug>

{
  "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 — veraltet

https://mcp.plane.so/sse wird nur aus Gründen der Abwärtskompatibilität gepflegt. Verwenden Sie stattdessen einen HTTP-Transport.

Werkzeuge

Der Server bietet 28 Werkzeuge an, eines pro Ressource. Jedes nimmt einen action-Parameter entgegen, der die Operation auswählt:

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

Die Beschreibung jedes Werkzeugs listet seine Aktionen mit ihren erforderlichen und optionalen Parametern auf, sodass der Katalog zum Aufrufzeitpunkt selbstdokumentierend ist.

→ Vollständige Werkzeug- und Aktionsreferenz

Arbeitselemente abfragen

List, count und search akzeptieren PQL, die Abfragesprache von Plane:

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

Rufen Sie get_pql_reference für die vollständige Syntax, Operatoren und ausgearbeitete Beispiele auf.

Upgrade von den Einzel-Operations-Werkzeugen

Frühere Versionen stellten ein Werkzeug pro API-Operation bereit. Bestehende Integrationen funktionieren weiterhin: 169 dieser 177 Namen lösen weiterhin auf das konsolidierte Werkzeug auf, sodass ein gespeicherter Prompt oder ein Skript, das create_work_item oder list_cycles aufruft, keine Änderung benötigt. Sie werden nicht mehr beworben und behalten die Parameternamen, mit denen sie ausgeliefert wurden (work_item_id, nicht workitem_id).

Sieben Namen wählten zwischen zwei Operationen mit einem Parameter (manage_project_archive(archive=False)), was ein einzelnes Werkzeug-Aktions-Paar nicht reproduzieren kann; der Aufruf eines davon nennt Ihnen den Ersatz. get_pql_reference ist unverändert.

Konfiguration

Authentifizierung

Variable	Erforderlich für	Zweck
PLANE_API_KEY	stdio	API-Key
PLANE_WORKSPACE_SLUG	stdio	Ziel-Workspace
PLANE_BASE_URL	optional	Plane-API-URL (Standard: https://api.plane.so)

Die Remote-Transporte übertragen Anmeldedaten in der Verbindung — der OAuth-Ablauf oder die PAT-Header — und benötigen keine davon.

Beim Selbst-Hosting des Servers:

Variable	Zweck
PLANE_INTERNAL_BASE_URL	Interne URL für Server-zu-Server-Aufrufe, bevorzugt gegenüber PLANE_BASE_URL
REDIS_HOST / REDIS_PORT	OAuth-Tokenspeicher; fällt auf In-Memory zurück
PLANE_OAUTH_PROVIDER_*	OAuth-Client-Anmeldedaten und Basis-URL
MCP_PATH_PREFIX	Pfadpräfix für die HTTP-Routen, wenn hinter einem Proxy bereitgestellt — /plane bedient /plane/http/mcp

OAuth-Weiterleitungs-URIs

Die OAuth-Transporte validieren die Weiterleitungs-URI jedes Clients gegen eine Zulassungsliste. Häufige Clients (Cursor, VS Code, Claude.ai, ChatGPT-Konnektoren, localhost) sind standardmäßig zugelassen.

Um einen neuen Client ohne Release aufzunehmen, fügen Sie Muster hinzu:

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

* passt auf jeden Port, jedes Pfadsegment oder jede Subdomain. Halten Sie den Host fest und verwenden Sie Wildcards nur für Port oder Pfad.

Protokollierung

Strukturiertes JSON. Jeder Werkzeugaufruf protokolliert seinen Namen, die Dauer, den Status und — sofern verfügbar — eine undurchsichtige Benutzer-ID und den Workspace-Slug.

export LOG_USER_INFO=true    # also log the display name (PII); default false

Nur die OAuth- und PAT-Transporte tragen einen Anzeigenamen; stdio ist nicht betroffen.

Entwicklung

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

Führen Sie den Server gegen einen Workspace aus:

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

Die Suite läuft vollständig offline — jede Aktion jeder Ressource wird gegen einen Stellvertreter ausgeführt, der jeden Aufruf an die echte plane-sdk-Signatur bindet. Siehe plane_mcp/tools/README.md.

Live-Integrationstests werden übersprungen, es sei denn, Sie richten sie auf einen laufenden 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

Sie schreiben echte Daten in diesen Workspace.

Repository-Struktur

Pfad	Inhalt
plane_mcp/__main__.py	Einstiegspunkt; wählt den Transport aus argv[1]
plane_mcp/server.py	eine Factory pro Transport
plane_mcp/client.py	löst Anmeldedaten in einen plane-sdk-Client auf
plane_mcp/auth/	OAuth-Anbieter und Header-Authentifizierung
plane_mcp/tools/	die Werkzeugoberfläche: ein Modul pro Plane-Ressource
plane_mcp/toolkit/	gemeinsame Bausteine für die Werkzeugoberfläche
plane_mcp/pql_reference.py	PQL-Syntaxreferenz, die Modellen bereitgestellt wird

Mitwirken

Pull-Requests sind willkommen. Bitte führen Sie vor dem Einreichen pytest und ruff check aus; neue Werkzeuge sollten die in plane_mcp/tools/README.md beschriebenen Invarianten erfüllen.

Siehe CONTRIBUTING.md und CODE_OF_CONDUCT.md.

Migration vom Node.js-Server

@makeplane/plane-mcp-server (Node.js) ist veraltet und wird nicht mehr gepflegt. Diese Python-Implementierung ersetzt es.

Node.js	Python
PLANE_API_KEY	PLANE_API_KEY
PLANE_API_HOST_URL	PLANE_BASE_URL
PLANE_WORKSPACE_SLUG	PLANE_WORKSPACE_SLUG

Ersetzen Sie die command und args durch die stdio-Konfiguration in Schnellstart.

Lizenz

MIT — siehe LICENSE.