Plane

officiel

Le serveur MCP officiel de Plane permet l'intégration avec les API de Plane, offrant une automatisation complète par IA des projets, éléments de travail, cycles et plus encore.

GitHub

364

Que pouvez-vous faire avec Plane MCP ?

Créer et mettre à jour des éléments de travail — Demandez à votre assistant de créer un élément de travail comme « Corriger la connexion » ou de mettre à jour son état, sa priorité ou ses assignés via l’outil workitem.
Interroger les éléments de travail avec PQL — Utilisez le langage de requête de Plane pour lister, compter ou rechercher des éléments de travail avec des filtres comme state__group = "started" AND priority = "urgent".
Gérer les cycles et les modules — Archivez des cycles, listez les cycles de projet ou effectuez d’autres opérations sur les cycles/modules via les outils de ressources consolidés.
Gérer les pièces jointes depuis des URL — Déclenchez le téléchargement de pièces jointes depuis des URL externes, avec prise en charge du proxy pour le contrôle SSRF via upload_from_url.
Récupérer la référence de syntaxe PQL — Demandez la syntaxe PQL complète, les opérateurs et des exemples pratiques en appelant get_pql_reference.

Documentation

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

Interrogation des é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'une seule paire 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`	facultative	URL de l'API Plane (par 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.

Proxy sortant pour les téléversements de pièces jointes

HTTP_PROXY / HTTPS_PROXY / NO_PROXY (et leurs formes en minuscules) sont respectés pour la récupération de pièce jointe depuis une URL (upload_from_url). Lorsqu'un proxy s'applique à une requête donnée, le proxy — pas ce serveur — est le contrôle SSRF de cette requête : le serveur ne fige ni ne valide lui-même l'adresse résolue de la cible, car le proxy se connecte à la cible et la résout indépendamment. Définissez la portée de NO_PROXY et la politique de sortie du proxy en conséquence.

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) ; prioritaire sur hôte/port
`REDIS_HOST` / `REDIS_PORT`	Stockage des jetons OAuth ; repli en 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 fixé 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.