Plane

Servidor MCP de Plane

Un servidor de Model Context Protocol para Plane. Proporciona a un agente de IA herramientas para leer y gestionar proyectos, elementos de trabajo, ciclos, módulos, lanzamientos, clientes y más.

Construido sobre FastMCP y el plane-sdk oficial.

• 28 herramientas, una por recurso de Plane, que cubren 183 operaciones
• Local o remoto — stdio, HTTP streamable, SSE
• Autenticación por OAuth o clave API

Inicio rápido

Obtén una clave API de Plane: Workspace Settings → API tokens.

Añade esto a la configuración de tu cliente MCP:

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

uvx no requiere paso de instalación. Requiere Python 3.10+.

Para una instancia de Plane autoalojada, añade "PLANE_BASE_URL": "https://plane.example.com".

Transportes

stdio — local

Se ejecuta como subproceso de tu cliente MCP. Configuración como se muestra arriba; necesita PLANE_API_KEY y PLANE_WORKSPACE_SLUG.

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

HTTP con OAuth — alojado

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

El flujo de OAuth se gestiona en la conexión; no hay credenciales en tu configuración. Para clientes sin soporte nativo de MCP remoto, conecta con mcp-remote:

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

Requiere Node.js 22+.

HTTP con un token de acceso personal — alojado

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

Cabecera	Valor
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 — obsoleto

https://mcp.plane.so/sse se mantiene únicamente por compatibilidad hacia atrás. Utiliza un transporte HTTP en su lugar.

Herramientas

El servidor ofrece 28 herramientas, una por recurso. Cada una acepta un parámetro action que selecciona la operación:

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 descripción de cada herramienta enumera sus acciones con sus parámetros obligatorios y opcionales, de modo que el catálogo es autodocumentado en el momento de la llamada.

→ Referencia completa de herramientas y acciones

Consulta de elementos de trabajo

Listar, contar y buscar aceptan PQL, el lenguaje de consulta 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")

Llama a get_pql_reference para ver la sintaxis completa, los operadores y ejemplos prácticos.

Migración desde las herramientas por operación

Las versiones anteriores exponían una herramienta por operación de API. Las integraciones existentes siguen funcionando: 169 de esos 177 nombres siguen resolviéndose en la herramienta consolidada, por lo que un mensaje o script guardado que llame a create_work_item o list_cycles no necesita cambios. Ya no se anuncian, y conservan los nombres de parámetros con los que se lanzaron (work_item_id, no workitem_id).

Siete nombres elegían entre dos operaciones mediante un parámetro (manage_project_archive(archive=False)), algo que un único par herramienta-acción no puede reproducir; llamar a uno te indica su reemplazo. get_pql_reference no ha cambiado.

Configuración

Autenticación

Variable	Necesaria para	Propósito
PLANE_API_KEY	stdio	Clave API
PLANE_WORKSPACE_SLUG	stdio	Workspace de destino
PLANE_BASE_URL	opcional	URL de la API de Plane (por defecto https://api.plane.so)

Los transportes remotos llevan las credenciales en la conexión — el flujo de OAuth o las cabeceras PAT — y no necesitan ninguna de estas.

Autoalojamiento del propio servidor:

Variable	Propósito
PLANE_INTERNAL_BASE_URL	URL interna para llamadas servidor-a-servidor, preferida sobre PLANE_BASE_URL
REDIS_HOST / REDIS_PORT	Almacenamiento de tokens OAuth; recurre a memoria si no está presente
PLANE_OAUTH_PROVIDER_*	Credenciales del cliente OAuth y URL base
MCP_PATH_PREFIX	Prefijo de ruta para las rutas HTTP, cuando se monta detrás de un proxy — /plane sirve /plane/http/mcp

URI de redirección de OAuth

Los transportes OAuth validan la URI de redirección de cada cliente contra una lista de permisos. Los clientes habituales (Cursor, VS Code, Claude.ai, conectores de ChatGPT, localhost) están permitidos por defecto.

Para incorporar un nuevo cliente sin necesidad de una versión, añade patrones:

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

* coincide con cualquier puerto, segmento de ruta o subdominio. Mantén el host fijo y usa comodines solo en el puerto o la ruta.

Registro de eventos

JSON estructurado. Cada llamada de herramienta registra su nombre, duración, estado y — cuando está disponible — un identificador de usuario opaco y el slug del workspace.

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

Solo los transportes OAuth y PAT llevan un nombre visible; stdio no se ve afectado.

Desarrollo

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

Ejecuta el servidor contra un workspace:

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

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

El conjunto de pruebas se ejecuta completamente sin conexión — cada acción de cada recurso se ejecuta contra un sustituto que vincula cada llamada con la firma genuina de plane-sdk. Consulta plane_mcp/tools/README.md.

Las pruebas de integración en vivo se omiten a menos que las apuntes a un servidor en ejecución:

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

Escriben datos reales en ese workspace.

Estructura del repositorio

Ruta	Contenido
plane_mcp/__main__.py	punto de entrada; elige el transporte a partir de argv[1]
plane_mcp/server.py	una fábrica por transporte
plane_mcp/client.py	resuelve las credenciales en un cliente plane-sdk
plane_mcp/auth/	proveedor de OAuth y autenticación por cabeceras
plane_mcp/tools/	la superficie de herramientas: un módulo por recurso de Plane
plane_mcp/toolkit/	bloques de construcción compartidos para la superficie de herramientas
plane_mcp/pql_reference.py	referencia de sintaxis PQL servida a los modelos

Contribuciones

Aceptamos pull requests. Ejecuta pytest y ruff check antes de enviar; las nuevas herramientas deben incluir los invariantes descritos en plane_mcp/tools/README.md.

Consulta CONTRIBUTING.md y CODE_OF_CONDUCT.md.

Migración desde el servidor Node.js

@makeplane/plane-mcp-server (Node.js) está obsoleto y sin mantenimiento. Esta implementación en Python lo reemplaza.

Node.js	Python
PLANE_API_KEY	PLANE_API_KEY
PLANE_API_HOST_URL	PLANE_BASE_URL
PLANE_WORKSPACE_SLUG	PLANE_WORKSPACE_SLUG

Reemplaza command y args con la configuración stdio que aparece en Inicio rápido.

Licencia

MIT — consulta LICENSE.