plane-mcp-server

Un servidor MCP (Model Context Protocol) para Plane autohospedado (Community Edition). Ofrece a Claude 56 herramientas que cubren proyectos, elementos de trabajo, estados, etiquetas, ciclos, módulos, comentarios, historial de actividad, enlaces, miembros y triaje de recepción, suficiente para actuar como gestor de proyectos en todos los proyectos de tu espacio de trabajo de Plane, desde una sesión de chat local.

Construido sobre la API REST pública de Plane (/api/v1), documentada en developers.plane.so. Community Edition cubre proyectos, elementos de trabajo, ciclos, módulos, recepción y estados/etiquetas; este servidor se ciñe a esa superficie. Épicas, iniciativas, espacios de equipo y clientes son funciones exclusivas de Plane Commercial/Cloud y no se incluyen a propósito.

Configuración

1. Genera una clave de API de Plane

En tu instancia de Plane: Configuración de perfil → Tokens de acceso personal → Añadir token de acceso personal.

2. Instala las dependencias y compila

cd plane-mcp-server
npm install
npm run build

3. Configura las variables de entorno

Copia .env.example a .env como referencia, pero ten en cuenta: los clientes MCP (Claude Desktop, Claude Code) pasan las variables de entorno directamente en su configuración, no a través de un archivo .env cargado por este proceso.

4. Añádelo a tu cliente MCP

Claude Code (claude mcp add o edita .mcp.json):

{
  "mcpServers": {
    "plane": {
      "command": "node",
      "args": ["/absolute/path/to/plane-mcp-server/dist/index.js"],
      "env": {
        "PLANE_BASE_URL": "https://plane.mycompany.com",
        "PLANE_API_KEY": "plane_api_xxxxxxxxxxxxxxxxxxxx",
        "PLANE_WORKSPACE_SLUG": "acme"
      }
    }
  }
}

Claude Desktop (claude_desktop_config.json): el mismo bloque mcpServers de arriba.

Reinicia el cliente después de editar la configuración. Deberías ver el servidor plane conectarse con 56 herramientas disponibles.

Related MCP server: plane-selfhost-mcp

Lo que puede hacer

• Proyectos — listar/obtener/crear/actualizar/archivar/eliminar, llevando el seguimiento de todos los proyectos de un espacio de trabajo a la vez.

• Elementos de trabajo (issues) — CRUD completo, búsqueda por UUID o identificador humano (ENG-123), búsqueda de texto libre y búsqueda avanzada con filtros estructurados (por estado, prioridad, asignado, etiquetas).

• Estados y etiquetas — inspecciona y gestiona las columnas de flujo de trabajo y las etiquetas de cada proyecto.

• Ciclos (sprints) — crear/actualizar/eliminar, asignar o quitar elementos de trabajo, leer contadores de progreso para informes de estado.

• Módulos — el mismo ciclo de vida que los ciclos, para agrupaciones de funcionalidades de mayor duración.

• Comentarios y actividad — leer/escribir hilos de discusión, leer el registro de auditoría de los cambios de campos en un elemento de trabajo.

• Enlaces — adjuntar PRs/documentos/diseños a un elemento de trabajo.

• Miembros — resolver nombres/correos de personas a UUIDs, asignar personal a proyectos, cambiar roles.

• Recepción — hacer triaje de las solicitudes entrantes (aceptar/rechazar/posponer/duplicar) antes de que lleguen al backlog.

Toda herramienta de listado/obtención acepta response_format: "markdown" | "json" (markdown por defecto, para legibilidad; json para uso programático posterior), y toda herramienta que necesite un espacio de trabajo usa PLANE_WORKSPACE_SLUG por defecto si has configurado uno, por lo que la mayoría de las llamadas solo necesitan un project_id.

No implementado

Excluidas deliberadamente para mantener el alcance centrado y solo CE: subida de archivos/adjuntos, páginas, estimaciones, seguimiento de tiempo (worklogs), tipos/propiedades personalizados de elementos de trabajo, y las APIs exclusivas comerciales de épicas/iniciativas/espacios de equipo/clientes/IDP-sync. Se pueden añadir más adelante siguiendo el mismo patrón en src/tools/.

Una sesión típica de PM multi-proyecto

1. plane_list_projects — ver todo en el espacio de trabajo.

2. plane_advanced_search_work_items en el proyecto activo con un filtro de prioridad/estado — encontrar lo urgente. Está acotado al proyecto, así que llámalo una vez por proyecto para cubrir todo el espacio de trabajo.

3. plane_list_cycles en el proyecto activo, luego plane_list_cycle_work_items — comprobar el estado del sprint actual.

4. plane_update_work_item — mover elementos entre estados, reasignar, repriorizar.

5. plane_add_work_item_comment — dejar notas de estado.

6. plane_list_intake_issues + plane_update_intake_issue — vaciar la cola de triaje.

Desarrollo

npm run dev     # tsx watch, runs src/index.ts directly
npm run build   # compile to dist/
npm start       # run compiled dist/index.js

Prueba con el MCP Inspector:

npx @modelcontextprotocol/inspector node dist/index.js

(Configura PLANE_BASE_URL / PLANE_API_KEY / PLANE_WORKSPACE_SLUG en el panel de entorno del Inspector).

Notas sobre la estabilidad de los endpoints

Este servidor se construyó a partir de la documentación de la API alojada de Plane (developers.plane.so) y del comportamiento de autohospedaje documentado: las instancias autohospedadas comparten la misma superficie /api/v1, pero el comportamiento exacto puede variar ligeramente según la versión de Plane. Si una herramienta menos común (p. ej. la sintaxis de filtro de plane_advanced_search_work_items) devuelve un 400/404 en tu instancia, prefiere las herramientas más simples plane_list_work_items / plane_list_states / plane_list_labels y filtra en el cliente, o consulta la documentación de la API de tu propia instancia en <your-plane-url>/api/ si está expuesta.