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.

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

Démarrage rapide

Obtenez une clé API depuis Plane : Workspace Settings → API tokens.

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 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 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 support natif 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 n'est maintenu que pour la rétrocompatibilité. Utilisez plutôt un transport HTTP.

Outils

Le serveur annonce 28 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 optionnels, 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 précédentes 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 une invite ou un script enregistré 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 via un paramètre (manage_project_archive(archive=False)), ce qu'un seul couple outil-action ne peut pas reproduire ; les appeler vous indique leur 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	optionnelle	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_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 contre une liste blanche. Les clients courants (Cursor, VS Code, Claude.ai, connecteurs ChatGPT, localhost) sont autorisés par défaut.

Pour intégrer un nouveau client sans publier de version, 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 le 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=true    # also log the display name (PII); default false

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

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

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

Contribuer

Les pull requests 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 le command et le args par la configuration stdio dans Démarrage rapide.

Licence

MIT — voir LICENSE.