planka-mcp

Controla un tablero de Planka 2.x desde Claude Code mediante 15 herramientas MCP. Las escrituras se releen y verifican, por lo que un éxito informado coincide con el tablero. Un flujo de trabajo opcional convierte ese tablero en memoria duradera para el trabajo de agentes.

Leer en español

You talk to Claude Code
          │
          ▼
  planka-mcp (stdio) ─── HTTPS + JSON ───▶ Planka 2.x
          │                                  │
          └──── reads the result back ◀──────┘

[!ADVERTENCIA] El antiguo paquete @gogogadgetbytes/planka-mcp puede informar éxito mientras no hace nada en Planka 2.x. Lee los cuatro problemas de fallo silencioso antes de reemplazar una instalación existente.

¿Nuevo en MCP? Lee esto primero

MCP es un estándar que permite a Claude Code llamar a herramientas proporcionadas por otro programa. Este repositorio ejecuta un pequeño programa local que traduce esas llamadas a herramientas en solicitudes a la API de Planka. Necesita credenciales de Planka porque actúa como un usuario dedicado de Planka, no como el propio Claude. Las credenciales permanecen en tu máquina y nunca se escriben en el archivo .mcp.json a nivel de proyecto. Claude Code carga los servidores MCP cuando comienza una sesión, así que reinícialo después de la configuración o los cambios de configuración.

Related MCP server: Planka MCP Server

Requisitos

• Node.js 18 o más reciente y npm

• Una instancia de Planka 2.x accesible

• Un usuario dedicado de Planka que pueda ver el proyecto y el tablero objetivo

• Claude Code instalado y disponible como claude

• Un rol de gestor de proyectos solo si la configuración debe crear un tablero

Se admiten Linux y macOS. No se requiere el runtime de Bun.

Instalar en 5 minutos

Clona el repositorio y ejecuta el instalador guiado:

git clone https://github.com/omnicoreos/planka-mcp.git
cd planka-mcp
./scripts/setup.sh

La configuración solicita la URL de Planka, el correo electrónico o nombre de usuario del agente y la contraseña. Valida esas credenciales antes de escribir la configuración, te permite seleccionar o crear un tablero, y luego ejecuta una prueba de humo real de crear/etiquetar/comentar/eliminar.

Ofrece dos configuraciones de Claude Code:

En ambos casos, la configuración almacena las credenciales fuera de Git en ~/.config/planka-mcp/config.json con modo 0600 y crea el lanzador privado ~/.local/bin/planka-mcp. Una configuración de equipo generada no contiene contraseña:

{
  "mcpServers": {
    "planka": {
      "type": "stdio",
      "command": "${HOME}/.local/bin/planka-mcp",
      "args": []
    }
  }
}

El instalador es seguro de volver a ejecutar. Actualiza la entrada planka, reutiliza las listas y etiquetas de flujo de trabajo existentes y elimina su tarjeta temporal de prueba de humo.

Verifica que funciona

Primero, inspecciona la configuración de Claude Code:

claude mcp list
claude mcp get planka

Luego reinicia Claude Code por completo. Si elegiste .mcp.json, abre Claude Code en ese proyecto y aprueba el servidor de ámbito de proyecto cuando se te solicite.

Pregunta a Claude Code:

Show me my Planka projects and boards. In the Pending list, create a card named
"MCP is working" with the description "Created from Claude Code", then read it back.

Si Claude no puede ver las herramientas, reinicia primero y luego sigue Solución de problemas.

Las 15 herramientas

Los IDs son cadenas. Comienza con planka_get_structure, luego usa los IDs devueltos por Planka; no los adivines.

Cada campo de entrada y una carga útil completa para cada herramienta están en Referencia de herramientas.

Flujo de trabajo opcional para agentes

El servidor MCP funciona por sí solo. El método opcional resuelve un problema diferente: preservar por qué existe el trabajo, qué cambió y qué sigue siendo cierto entre sesiones de agentes.

Adóptalo por capas:

1. Usa solo las herramientas MCP.

2. Añade los estados del tablero, la plantilla de tarjeta y los apretones de manos humanos.

3. Añade un worktree por tarjeta con un director que coordine a los trabajadores.

Comienza con Un tablero que sobrevive a la sesión. La plantilla de tablero, las habilidades de Claude Code copiables y el ayudante de worktree opcional son piezas independientes.

Solución de problemas

• Síntomas, causas y correcciones exactas

• Por qué Planka 2.x rompe silenciosamente los servidores MCP antiguos

• Cargas útiles completas de herramientas

Al informar de un error, incluye la versión de Planka, la versión de Node, el nombre de la herramienta y el texto del error. Nunca pegues credenciales o tokens de acceso.

Créditos y licencia

Este es un fork con licencia MIT de gogogadgetbytes/planka-mcp, no una implementación original desde cero. Consulta CREDITS.md para la atribución ascendente, las correcciones mantenidas y las solicitudes de extracción sin respuesta.

Consulta LICENSE para los avisos de contribuyentes originales y actuales.

Desarrollo

npm ci
npm run build
npm test

La prueba de humo real es opcional porque muta un tablero escribible y luego se limpia a sí misma:

export PLANKA_BASE_URL="https://planka.example.com"
export PLANKA_AGENT_EMAIL="agent@example.com"
export PLANKA_AGENT_PASSWORD="<YOUR_PASSWORD>"
export PLANKA_SMOKE_BOARD_ID="1234567890123456789"
npm run test:smoke

Consulta CONTRIBUTING.md antes de abrir un cambio. La identidad de lanzamiento está centralizada en project.identity.json; actualízala y ejecuta npm run sync:identity antes de publicar bajo tu propio espacio de nombres.