Planka v2

Conecta Claude, Cursor, Codex y otros clientes MCP directamente a tus tableros de Planka v2.x.

Documentación

Planka v2.x MCP

Conecta Claude, Cursor, Codex y otros clientes MCP directamente a tus tableros de Planka v2.x.

Dale a tus agentes de IA acceso estructurado y seguro a proyectos, tableros, tarjetas, tareas, comentarios, etiquetas y flujos de trabajo a través del Protocolo de Contexto de Modelo (MCP).

[!IMPORTANT] Construido específicamente para Planka v2.x. Este MCP no es compatible con Planka v1.x.

¿Por qué Planka MCP?

Planka ofrece una excelente interfaz web para usuarios humanos. Sin embargo, los agentes de IA necesitan acceso estructurado a proyectos, tableros, tarjetas, tareas, comentarios y flujos de trabajo.

Este servidor MCP expone la API de Planka v2 a través del Protocolo de Contexto de Modelo (MCP), permitiendo que Claude, Cursor, Codex y otros agentes de IA interactúen con Planka usando lenguaje natural.

Versiones de Planka Compatibles

Versión de Planka	Estado
2.0.0-rc.2	✅ Probada
2.1.1	✅ Probada
2.2.1	✅ Probada
2.x más recientes	⚠️ Se espera que funcione

Características

Gestión completa de proyectos y tableros
Gestión completa del ciclo de vida de tarjetas
Soporte para listas de tareas y tareas
Comentarios, etiquetas y asignaciones
Seguimiento de tiempo en tarjetas
Resúmenes de proyectos y tableros
Interfaz de herramientas nativa de MCP
Soporte para los principales clientes MCP
Soporte para Planka autoalojado y en la nube

Conversaciones de Ejemplo

Configuración de Proyecto

Usuario

Crea un proyecto llamado "Rediseño del Sitio Web" con tableros "Pendiente", "En Progreso" y "Terminado".

Asistente

✓ Created project "Website Redesign"
✓ Created board "Backlog"
✓ Created board "In Progress"
✓ Created board "Done"

Project setup completed successfully.

Creación de Tareas

Usuario

Crea una tarjeta "Implementar autenticación" en el tablero Pendiente con tareas:

Diseñar flujo de inicio de sesión

Implementar autenticación JWT

Añadir restablecimiento de contraseña

Escribir pruebas

Asistente

✓ Created card "Implement authentication"
✓ Created task list
✓ Added 4 tasks

Automatización de Flujos de Trabajo

Usuario

Encuentra todas las tarjetas vencidas asignadas a mí, muévelas a "Bloqueado", añade un comentario explicando el motivo y genera un resumen del proyecto.

Asistente

✓ Found 7 overdue cards
✓ Moved cards to "Blocked"
✓ Added explanatory comments
✓ Generated updated project summary

Herramientas Disponibles

Nombre de la Herramienta	Acciones	Descripción
`project_board_manager`	`get_projects` · `create_project` · `get_project` · `update_project` · `delete_project` · `get_boards` · `create_board` · `get_board` · `update_board` · `delete_board` · `get_board_summary` · `get_project_summary`	Proyectos y tableros, incluidos resúmenes agregados
`list_manager`	`get_all` · `create` · `get_one` · `update` · `delete`	Listas Kanban dentro de un tablero
`card_manager`	`get_all` · `create` · `get_one` · `update` · `move` · `duplicate` · `delete` · `create_with_tasks` · `get_details`	Tarjetas, incluida la creación en un solo paso con lista de verificación de tareas
`stopwatch`	`start` · `stop` · `get` · `reset`	Seguimiento de tiempo en una tarjeta
`label_manager`	`get_all` · `create` · `update` · `delete` · `add_to_card` · `remove_from_card`	Etiquetas de tablero y su asignación a tarjetas
`task_list_manager`	`get_all` · `create` · `get_one` · `update` · `delete`	Listas de tareas dentro de una tarjeta (entidad de Planka v2.0)
`task_manager`	`get_all` · `create` · `batch_create` · `get_one` · `update` · `delete` · `complete_task`	Tareas individuales, incluida la creación masiva
`comment_manager`	`get_all` · `create` · `get_one` · `update` · `delete`	Comentarios en una tarjeta
`membership_manager`	`get_all` · `create` · `get_one` · `update` · `delete`	Membresía y roles a nivel de tablero (`editor` / `viewer`)
`card_membership_manager`	`get_all` · `get_users` · `create` · `delete`	Asignar/eliminar miembros de tarjetas por ID, correo electrónico o nombre de usuario

card_manager con action: "get_details" incluye un array attachments con metadatos de solo lectura: IDs de adjuntos y tarjetas, ID de usuario creador, nombre, tipo, tipo MIME, tamaño, URL de descarga o enlace, y marcas de tiempo. No descarga ni devuelve el contenido de los adjuntos.

Inicio Rápido

Requisitos

Una instancia de Planka v2.x en ejecución
Una cuenta de usuario de Planka dedicada para tu agente de IA
Node.js 18+ (si se ejecuta localmente)

[!IMPORTANT] Después de crear la cuenta MCP, inicia sesión en la interfaz web de Planka con esa cuenta y acepta los términos de servicio antes de configurar o iniciar el servidor MCP. Esto es obligatorio para cada cuenta nueva.

Configura tu Cliente MCP

Cada cliente compatible con MCP usa el mismo comando subyacente: solo difiere la ubicación del archivo de configuración (y ocasionalmente el envoltorio JSON). Consulta Ejemplos de Configuración de Cliente a continuación para tu herramienta específica.

El bloque de configuración principal es siempre:

{
  "command": "npx",
  "args": ["-y", "@goldpulpy/planka-v2-mcp@latest"],
  "env": {
    "PLANKA_BASE_URL": "https://your-planka-instance.com",
    "PLANKA_AGENT_EMAIL": "agent@yourdomain.com",
    "PLANKA_AGENT_PASSWORD": "your-secure-password",
    "PLANKA_IGNORE_SSL": "true"
  }
}

Alternativa: ejecutar desde una compilación local

{
  "command": "node",
  "args": ["/absolute/path/to/planka-v2-mcp/dist/index.js"],
  "env": {
    "PLANKA_BASE_URL": "https://your-planka-instance.com",
    "PLANKA_AGENT_EMAIL": "agent@yourdomain.com",
    "PLANKA_AGENT_PASSWORD": "your-secure-password",
    "PLANKA_IGNORE_SSL": "true"
  }
}

Útil cuando estás contribuyendo al propio servidor o necesitas una compilación fija y sin conexión.

[!TIP] Establece PLANKA_IGNORE_SSL a "true" solo para certificados autofirmados en entornos confiables/locales: déjalo sin establecer en producción.

Verifica la Conexión

Pregunta primero a tu agente algo de solo lectura, por ejemplo, "Lista mis proyectos de Planka." Si obtienes una respuesta real, estás conectado correctamente.

Ejemplos de Configuración de Cliente

La mayoría de los clientes MCP comparten exactamente la misma forma JSON mcpServers: solo difiere la ubicación del archivo de configuración. Los clientes con un formato diferente (Codex, Continue, Zed) tienen su propio bloque a continuación.

Clientes estándar mcpServers - Claude Desktop, Claude Code, Cursor, Windsurf, Cline, Antigravity

{
  "mcpServers": {
    "planka-mcp": {
      "command": "npx",
      "args": ["-y", "@goldpulpy/planka-v2-mcp@latest"],
      "env": {
        "PLANKA_BASE_URL": "https://your-planka-instance.com",
        "PLANKA_AGENT_EMAIL": "agent@yourdomain.com",
        "PLANKA_AGENT_PASSWORD": "your-secure-password",
        "PLANKA_IGNORE_SSL": "true"
      }
    }
  }
}

Coloca este bloque en el archivo de configuración correspondiente:

Cliente	Archivo de configuración
Claude Desktop	macOS: `~/Library/Application Support/Claude/claude_desktop_config.json` · Windows: `%APPDATA%\Claude\claude_desktop_config.json`
Claude Code (CLI)	`.mcp.json` en la raíz de tu proyecto (o `claude mcp add`, ver más abajo)
Cursor	`~/.cursor/mcp.json` (global) o `.cursor/mcp.json` (proyecto)
Windsurf	`~/.codeium/windsurf/mcp_config.json`
Cline (VS Code)	`cline_mcp_settings.json`, a través de Cline → MCP Servers → Configure MCP Servers (añade `"disabled": false, "autoApprove": []` a la entrada del servidor)
Antigravity	A través de Settings → MCP Servers → Add Server, o directamente en su archivo de configuración

[!NOTE] Claude Code también admite añadir el servidor con un comando de una línea en lugar de editar JSON manualmente:
claude mcp add planka-mcp \
  --env PLANKA_BASE_URL=https://your-planka-instance.com \
  --env PLANKA_AGENT_EMAIL=agent@yourdomain.com \
  --env PLANKA_AGENT_PASSWORD=your-secure-password \
  --env PLANKA_IGNORE_SSL=true \
  -- npx -y @goldpulpy/planka-v2-mcp@latest

Reinicia el cliente después de guardar.

Codex CLI

Edita ~/.codex/config.toml:

[mcp_servers.planka-mcp]
command = "npx"
args = ["-y", "@goldpulpy/planka-v2-mcp@latest"]

[mcp_servers.planka-mcp.env]
PLANKA_BASE_URL = "https://your-planka-instance.com"
PLANKA_AGENT_EMAIL = "agent@yourdomain.com"
PLANKA_AGENT_PASSWORD = "your-secure-password"
PLANKA_IGNORE_SSL = "true"

O añádelo en una línea:

codex mcp add planka-mcp -- npx -y @goldpulpy/planka-v2-mcp@latest

luego establece las variables PLANKA_* en el bloque [mcp_servers.planka-mcp.env] generado.

Continue (extensión de VS Code / JetBrains)

Añade a ~/.continue/config.yaml:

mcpServers:
  - name: planka-mcp
    command: npx
    args:
      - -y
      - "@goldpulpy/planka-v2-mcp@latest"
    env:
      PLANKA_BASE_URL: https://your-planka-instance.com
      PLANKA_AGENT_EMAIL: agent@yourdomain.com
      PLANKA_AGENT_PASSWORD: your-secure-password
      PLANKA_IGNORE_SSL: "true"

Zed

Edita ~/.config/zed/settings.json (macOS/Linux) o %APPDATA%\Zed\settings.json (Windows), o ábrelo a través de Cmd+Shift+P → "zed: open settings":

{
  "context_servers": {
    "planka-mcp": {
      "source": "custom",
      "command": "npx",
      "args": ["-y", "@goldpulpy/planka-v2-mcp@latest"],
      "env": {
        "PLANKA_BASE_URL": "https://your-planka-instance.com",
        "PLANKA_AGENT_EMAIL": "agent@yourdomain.com",
        "PLANKA_AGENT_PASSWORD": "your-secure-password",
        "PLANKA_IGNORE_SSL": "true"
      }
    }
  }
}

"source": "custom" es obligatorio para servidores añadidos manualmente (a diferencia de los instalados mediante una extensión de Zed). Zed recarga el servidor automáticamente después de guardar: no se necesita reiniciar el editor.

Cualquier otro cliente compatible con MCP

El servidor es un servidor MCP estándar de stdio: cualquier cliente que admita la forma command / args / env funcionará. Apúntalo a:

npx -y @goldpulpy/planka-v2-mcp@latest

con las cuatro variables de entorno PLANKA_* configuradas como se muestra arriba.

Variables de Entorno

Variable	Requerida	Predeterminado	Descripción
`PLANKA_BASE_URL`	✅	-	URL completa de tu instancia de Planka
`PLANKA_AGENT_EMAIL`	✅	-	Correo de inicio de sesión para el usuario agente dedicado
`PLANKA_AGENT_PASSWORD`	✅	-	Contraseña para el usuario agente
`PLANKA_IGNORE_SSL`	❌	`false`	Omitir verificación SSL - solo certificados autofirmados/locales

Seguridad

La autenticación se realiza mediante una cuenta de usuario dedicada de Planka.
Las credenciales se suministran únicamente a través de variables de entorno.
El servidor MCP no persiste datos del tablero fuera del proceso en ejecución.
La verificación de certificados SSL está habilitada por defecto.
PLANKA_IGNORE_SSL=true solo debe usarse en entornos locales o autohospedados de confianza.

Solución de Problemas

El cliente no puede ver ninguna herramienta / la conexión falla silenciosamente

Confirma que PLANKA_BASE_URL no tenga una barra diagonal final y sea accesible desde la máquina que ejecuta el servidor MCP (no solo desde tu navegador).
Verifica que el usuario agente pueda iniciar sesión con esas credenciales exactas a través de la interfaz web normal de Planka y haya aceptado los términos de servicio.

Errores de SSL / certificados

Si tu instancia utiliza un certificado autofirmado, configura "PLANKA_IGNORE_SSL": "true". Evita esto en producción; prefiere un certificado válido en su lugar.

Las tarjetas se crean pero las listas de verificación/subtareas no se muestran

Asegúrate de que el tipo de tarjeta sea "project" (el predeterminado). Las tarjetas creadas como tipo "story" no exponen Listas de Tareas de la misma manera.

Desarrollo

# Install dependencies
npm install

# Configure environment variables
cp .env.example .env

# Start the bundled Planka development instance
npm run planka:up

# Build the project
npm run build

# Run @modelcontextprotocol/inspector
npm run inspector

La instancia de desarrollo requiere Docker Compose y está disponible en http://localhost:3000 (inicio de sesión: admin@example.com / admin). Actualiza .env con esa URL e inicio de sesión para uso local. Como con cualquier cuenta MCP recién creada, inicia sesión a través del navegador y acepta los términos de servicio antes de usar la cuenta con el servidor MCP. Detén la instancia conservando sus datos con npm run planka:down, o detenla y elimina sus volúmenes con npm run planka:clear.

Sembrar un Tablero de Demostración

El comando de siembra solo para desarrollo crea un tablero representativo para pruebas locales y demostraciones. Instala las dependencias del proyecto y configura .env con una instancia de Planka v2 accesible y valores válidos de PLANKA_BASE_URL, PLANKA_AGENT_EMAIL y PLANKA_AGENT_PASSWORD antes de ejecutarlo.

# Reuse or create the private "Demo Project", then create "Demo Board"
npm run seed

# Seed an existing project
npm run seed -- --project-id <project-id>

# Choose a different board name
npm run seed -- --project-id <project-id> --board-name "My Demo Board"

# Show all options
npm run seed -- --help

El tablero incluye tarjetas en las listas de flujo de trabajo predeterminadas, descripciones, fechas de vencimiento relativas, etiquetas de Planka usadas como etiquetas, listas de tareas, tareas completadas e incompletas, y comentarios. El comando imprime el ID del proyecto, ID del tablero, nombre del tablero y recuentos de recursos cuando tiene éxito.

El comando de siembra se niega a modificar un proyecto que ya contiene un tablero con el nombre exacto solicitado; usa --board-name para elegir otro nombre. Si ocurre un error después de la creación del tablero, el comando informa la etapa fallida y el ID del tablero y deja el tablero parcialmente poblado disponible para inspección. Elimina ese tablero en Planka antes de reintentar con el mismo nombre.

La fuente de siembra y su salida .seed-dist/ compilada por separado son solo para desarrollo y no están incluidas en la compilación del servidor MCP ni en el paquete publicado.

Contribuciones

Las contribuciones son bienvenidas. Consulta CONTRIBUTING.md para más detalles.

Agradecimientos

Este proyecto es una bifurcación de Navya-Tecnologia/planka-v2-mcp, que se basa en bradrisse/kanban-mcp. Gracias a @virapa y @bradrisse por la base detrás de este código.

Licencia

Licenciado bajo la Licencia MIT. Consulta LICENSE para más detalles.

Este proyecto se centra exclusivamente en la interfaz MCP. Para la configuración del servidor de Planka en sí, consulta la documentación oficial de Planka.