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, versiones, clientes y más.

Construido sobre FastMCP y el plane-sdk oficial.

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

Inicio rápido

Obtén una clave API de Plane: Configuración del espacio de trabajo → Tokens de API.

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 un 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 al conectar; no se necesitan credenciales en tu configuración. Para clientes sin soporte nativo de MCP remoto, usa un puente 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 con versiones anteriores. Usa un transporte HTTP en su lugar.

Herramientas

El servidor anuncia 30 herramientas, una por recurso. Cada una toma 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, por lo que el catálogo se autodocumenta 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, operadores y ejemplos prácticos.

Actualizació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 a la herramienta consolidada, por lo que una instrucción 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 publicaron (work_item_id, no workitem_id).

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

Configuración

Autenticación

Variable	Requerida para	Propósito
PLANE_API_KEY	stdio	Clave API
PLANE_WORKSPACE_SLUG	stdio	Espacio de trabajo 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_URL	Almacenamiento de tokens OAuth como una URL de conexión (redis:// o rediss:// para TLS); tiene prioridad sobre host/puerto
REDIS_HOST / REDIS_PORT	Almacenamiento de tokens OAuth; recurre a memoria
PLANE_OAUTH_PROVIDER_*	Credenciales de 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 OAuth

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

Para incorporar un nuevo cliente sin publicar 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 para el puerto o la ruta.

Registro de actividad

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 espacio de trabajo.

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

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 espacio de trabajo:

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

Pruebas, formato y 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 real 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 espacio de trabajo.

Estructura del repositorio

Ruta	Contenido
plane_mcp/__main__.py	punto de entrada; elige el transporte según argv[1]
plane_mcp/server.py	una fábrica por transporte
plane_mcp/client.py	resuelve credenciales en un cliente plane-sdk
plane_mcp/auth/	proveedor OAuth y autenticación por cabecera
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

Las solicitudes de extracción son bienvenidas. 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 de Inicio rápido.

Licencia

MIT — consulta LICENSE.