Plane

Serveur MCP Plane

Un serveur Model Context Protocol pour Plane. Fournit à un agent IA des outils pour lire et gérer des projets, des éléments de travail, des cycles, des modules, des versions, des clients et plus encore.

Construit sur FastMCP et le plane-sdk officiel.

• 30 outils, un par ressource Plane, couvrant 207 opérations
• Local ou distant — stdio, HTTP streamable, SSE
• Authentification OAuth ou par clé API

Démarrage rapide

Obtenez une clé API depuis Plane : Paramètres de l'espace de travail → Jetons API.

Ajoutez ceci à la configuration de votre client MCP :

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

uvx ne nécessite aucune étape d'installation. Requiert Python 3.10+.

Pour une instance Plane auto-hébergée, ajoutez "PLANE_BASE_URL": "https://plane.example.com".

Transports

stdio — local

S'exécute comme sous-processus de votre client MCP. Configuration comme indiqué ci-dessus ; nécessite PLANE_API_KEY et PLANE_WORKSPACE_SLUG.

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

HTTP avec OAuth — hébergé

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

Le flux OAuth est géré à la connexion ; aucune information d'identification dans votre configuration. Pour les clients sans prise en charge native du MCP distant, faites le pont avec mcp-remote :

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

Requiert Node.js 22+.

HTTP avec un jeton d'accès personnel — hébergé

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

En-tête	Valeur
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 — obsolète

https://mcp.plane.so/sse est maintenu uniquement pour la rétrocompatibilité. Utilisez un transport HTTP à la place.

Outils

Le serveur annonce 30 outils, un par ressource. Chacun prend un paramètre action qui sélectionne l'opération :

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

La description de chaque outil liste ses actions avec leurs paramètres requis et facultatifs, de sorte que le catalogue est auto-documenté au moment de l'appel.

→ Référence complète des outils et actions

Interroger les éléments de travail

Liste, comptage et recherche acceptent PQL, le langage de requête de 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")

Appelez get_pql_reference pour la syntaxe complète, les opérateurs et des exemples détaillés.

Migration depuis les outils par opération

Les versions antérieures exposaient un outil par opération d'API. Les intégrations existantes continuent de fonctionner : 169 de ces 177 noms résolvent toujours vers l'outil consolidé, donc un script ou une invite enregistrée appelant create_work_item ou list_cycles ne nécessite aucun changement. Ils ne sont plus annoncés et conservent les noms de paramètres avec lesquels ils ont été livrés (work_item_id, pas workitem_id).

Sept noms choisissaient entre deux opérations avec un paramètre (manage_project_archive(archive=False)), ce qu'un seul couple outil-action ne peut pas reproduire ; appeler l'un vous indique son remplaçant. get_pql_reference est inchangé.

Configuration

Authentification

Variable	Requise pour	Objectif
PLANE_API_KEY	stdio	Clé API
PLANE_WORKSPACE_SLUG	stdio	Espace de travail cible
PLANE_BASE_URL	facultatif	URL de l'API Plane (défaut https://api.plane.so)

Les transports distants transportent les informations d'identification dans la connexion — le flux OAuth ou les en-têtes PAT — et n'en nécessitent aucune.

Auto-hébergement du serveur lui-même :

Variable	Objectif
PLANE_INTERNAL_BASE_URL	URL interne pour les appels serveur à serveur, préférée à PLANE_BASE_URL
REDIS_URL	Stockage des jetons OAuth comme URL de connexion unique (redis:// ou rediss:// pour TLS) ; prime sur hôte/port
REDIS_HOST / REDIS_PORT	Stockage des jetons OAuth ; repli sur la mémoire
PLANE_OAUTH_PROVIDER_*	Informations d'identification du client OAuth et URL de base
MCP_PATH_PREFIX	Préfixe de chemin pour les routes HTTP, lorsqu'il est monté derrière un proxy — /plane sert /plane/http/mcp

URI de redirection OAuth

Les transports OAuth valident l'URI de redirection de chaque client par rapport à une liste autorisée. Les clients courants (Cursor, VS Code, Claude.ai, connecteurs ChatGPT, localhost) sont autorisés par défaut.

Pour intégrer un nouveau client sans publication, ajoutez des motifs :

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

* correspond à n'importe quel port, segment de chemin ou sous-domaine. Gardez l'hôte épinglé et utilisez un caractère générique uniquement pour le port ou le chemin.

Journalisation

JSON structuré. Chaque appel d'outil journalise son nom, sa durée, son statut et — lorsque disponible — un identifiant utilisateur opaque et le slug de l'espace de travail.

export LOG_USER_INFO=false    # also log the display name (PII);
export LOG_PAYLOADS=false    # keep request payloads out of logs; default true

Seuls les transports OAuth et PAT portent un nom d'affichage ; stdio n'est pas affecté.

Développement

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

Exécutez le serveur contre un espace de travail :

PLANE_API_KEY=... PLANE_WORKSPACE_SLUG=... python -m plane_mcp stdio
python -m plane_mcp http            # port 8211

Tests, formatage, 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

La suite s'exécute entièrement hors ligne — chaque action de chaque ressource est exécutée contre un substitut qui lie chaque appel à la signature plane-sdk authentique. Voir plane_mcp/tools/README.md.

Les tests d'intégration en direct sont ignorés sauf si vous les pointez vers un serveur en cours d'exécution :

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

Ils écrivent des données réelles dans cet espace de travail.

Structure du dépôt

Chemin	Contenu
plane_mcp/__main__.py	point d'entrée ; choisit le transport depuis argv[1]
plane_mcp/server.py	une fabrique par transport
plane_mcp/client.py	résout les informations d'identification en un client plane-sdk
plane_mcp/auth/	fournisseur OAuth et authentification par en-tête
plane_mcp/tools/	la surface d'outils : un module par ressource Plane
plane_mcp/toolkit/	blocs de construction partagés pour la surface d'outils
plane_mcp/pql_reference.py	référence de syntaxe PQL servie aux modèles

Contribution

Les demandes de tirage sont les bienvenues. Veuillez exécuter pytest et ruff check avant de soumettre ; les nouveaux outils doivent être accompagnés des invariants décrits dans plane_mcp/tools/README.md.

Voir CONTRIBUTING.md et CODE_OF_CONDUCT.md.

Migration depuis le serveur Node.js

@makeplane/plane-mcp-server (Node.js) est obsolète et non maintenu. Cette implémentation Python le remplace.

Node.js	Python
PLANE_API_KEY	PLANE_API_KEY
PLANE_API_HOST_URL	PLANE_BASE_URL
PLANE_WORKSPACE_SLUG	PLANE_WORKSPACE_SLUG

Remplacez command et args par la configuration stdio dans Démarrage rapide.

Licence

MIT — voir LICENSE.