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.

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

Schnellstart

Holen Sie sich einen API-Key von Plane: Workspace-Einstellungen → 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 einem persönlichen 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 30 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 Zeitpunkt des Aufrufs selbstdokumentierend ist.

→ Vollständige Werkzeug- und Aktionsreferenz

Arbeitselemente abfragen

Liste, Anzahl und Suche 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 Beispiele auf.

Upgrade von den pro-Operation-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 Werkzeug-Aktions-Paar nicht reproduzieren kann; der Aufruf eines davon teilt Ihnen seinen Ersatz mit. 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.

Selbsthosting des Servers selbst:

Variable	Zweck
PLANE_INTERNAL_BASE_URL	Interne URL für Server-zu-Server-Aufrufe, bevorzugt gegenüber PLANE_BASE_URL
REDIS_URL	OAuth-Tokenspeicher als eine Verbindungs-URL (redis:// oder rediss:// für TLS); hat Vorrang vor Host/Port
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. Gängige Clients (Cursor, VS Code, Claude.ai, ChatGPT-Konnektoren, localhost) sind standardmäßig zugelassen.

Um einen neuen Client ohne Release anzubinden, 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, seine Dauer, seinen Status und — wenn verfügbar — eine undurchsichtige Benutzer-ID und den 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

Nur die OAuth- und PAT-Transporte führen 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, Formatierung, 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 mit den Invarianten kommen, die in plane_mcp/tools/README.md beschrieben sind.

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 ihn.

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.