MCP Planka Server

Servidor MCP (Model Context Protocol) para integración completa con tableros Kanban de Planka. Permite gestionar proyectos, tableros, tarjetas, tareas y colaboración directamente desde aplicaciones MCP como Claude.

🚀 Características

Gestión de Proyectos: Crear, listar y administrar proyectos
Tableros Kanban: Crear y gestionar tableros con listas personalizadas
Gestión de Tarjetas: Crear, mover, duplicar y organizar tarjetas
Sistema de Tareas: Crear subtareas y seguimiento de progreso
Etiquetas y Categorías: Organizar tarjetas con etiquetas de colores
Comentarios: Colaboración a través de comentarios en tarjetas
Seguimiento de Tiempo: Cronómetros integrados para time tracking
Gestión de Membresías: Control de acceso y permisos por tablero

📋 Herramientas Disponibles

`mcp_kanban_project_board_manager`

Gestiona proyectos y tableros con operaciones CRUD completas.

Parámetros: action, id, projectId, name, position, boardId

`mcp_kanban_list_manager`

Administra listas dentro de los tableros.

Parámetros: action, id, boardId, name, position

`mcp_kanban_card_manager`

Gestión completa de tarjetas Kanban.

Parámetros: action, id, listId, name, description, tasks

`mcp_kanban_stopwatch`

Control de cronómetros para seguimiento de tiempo.

Parámetros: action, id

`mcp_kanban_label_manager`

Gestión de etiquetas y categorización.

Parámetros: action, boardId, name, color, cardId, labelId

`mcp_kanban_task_manager`

Control de tareas y subtareas.

Parámetros: action, cardId, name, tasks, isCompleted

`mcp_kanban_comment_manager`

Sistema de comentarios para colaboración.

Parámetros: action, cardId, text

`mcp_kanban_membership_manager`

Control de acceso y permisos por tablero.

Parámetros: action, boardId, userId, role, canComment

🛠️ Instalación

Instalación General MCP EN LOCAL (NO RECOMENDADO)

Instalar dependencias:

npm install

Configurar variables de entorno:

cp config.example.env .env
# Editar .env con la configuración de su servidor Planka

Compilar:

npm run build

⚙️ Configuración

Variables de Entorno

Variable	Descripción	Por Defecto
`PLANKA_BASE_URL`	URL base del servidor Planka	`http://localhost:3000`
`PLANKA_AGENT_EMAIL`	Email para autenticación	-
`PLANKA_AGENT_PASSWORD`	Contraseña para autenticación	-
`PLANKA_ALLOW_INSECURE`	Permitir conexiones HTTPS sin validar certificado SSL (útil para certificados autofirmados o internos)	`false`

Configuración MCP en Aplicaciones USANDO NPX (RECOMENDADO)

Ubicación del archivo de configuración

Claude Desktop:

Windows: %APPDATA%\Claude\claude_desktop_config.json
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Linux: ~/.config/claude/claude_desktop_config.json

Para Claude Desktop (config.json)

Configuración básica con NPX (RECOMENDADO):

{
  "mcpServers": {
    "planka": {
      "command": "npx",
      "args": ["@grec0/mcp-planka@latest"],
      "env": {
        "PLANKA_BASE_URL": "http://localhost:3000",
        "PLANKA_AGENT_EMAIL": "[email protected]",
        "PLANKA_AGENT_PASSWORD": "demo"
      }
    }
  }
}

⚠️ IMPORTANTE: Usar @latest garantiza que se use la versión más reciente del paquete. Sin esto, puedes obtener errores como "no server info found".

Para servidor Planka remoto:

{
  "mcpServers": {
    "planka": {
      "command": "npx",
      "args": ["@grec0/mcp-planka@latest"],
      "env": {
        "PLANKA_BASE_URL": "https://tu-planka-server.com",
        "PLANKA_AGENT_EMAIL": "[email protected]",
        "PLANKA_AGENT_PASSWORD": "tu-contraseña"
      }
    }
  }
}

Para servidor Planka con certificado SSL autofirmado o interno:

{
  "mcpServers": {
    "planka": {
      "command": "npx",
      "args": ["@grec0/mcp-planka@latest"],
      "env": {
        "PLANKA_BASE_URL": "https://planka-interno.empresa.com",
        "PLANKA_AGENT_EMAIL": "[email protected]",
        "PLANKA_AGENT_PASSWORD": "tu-contraseña",
        "PLANKA_ALLOW_INSECURE": "true"
      }
    }
  }
}

Para instalación local

{
  "mcpServers": {
    "planka": {
      "command": "node",
      "args": ["C:/ruta/a/kanban-mcp/dist/index.js"],
      "env": {
        "PLANKA_BASE_URL": "http://localhost:3000",
        "PLANKA_AGENT_EMAIL": "[email protected]",
        "PLANKA_AGENT_PASSWORD": "demo"
      }
    }
  }
}

Para entorno de desarrollo

{
  "mcpServers": {
    "planka": {
      "command": "npm",
      "args": ["run", "dev"],
      "cwd": "C:/ruta/a/kanban-mcp",
      "env": {
        "PLANKA_BASE_URL": "http://localhost:3000",
        "PLANKA_AGENT_EMAIL": "[email protected]",
        "PLANKA_AGENT_PASSWORD": "demo"
      }
    }
  }
}

Verificar configuración MCP

Después de configurar el MCP, puedes verificar que funciona correctamente:

Reiniciar la aplicación (Claude Desktop, etc.)

Probar operación básica:

mcp_kanban_project_board_manager(action: "get_projects", page: 1, perPage: 10)

Crear un tablero de prueba:

mcp_kanban_project_board_manager(action: "create_board", projectId: "ID_DEL_PROYECTO", name: "Tablero de Prueba", position: 1)

🔧 Solución de Problemas

Error: "no server info found"

Este error típicamente ocurre por:

Falta el @latest en la configuración:

// ❌ INCORRECTO
"args": ["@grec0/mcp-planka"]

// ✅ CORRECTO  
"args": ["@grec0/mcp-planka@latest"]

Variables de entorno faltantes o incorrectas:

"env": {
  "PLANKA_BASE_URL": "http://localhost:3000",
  "PLANKA_AGENT_EMAIL": "[email protected]", 
  "PLANKA_AGENT_PASSWORD": "demo"
}

El servidor Planka no está ejecutándose:
- Verificar que Planka esté en http://localhost:3000
- Verificar que las credenciales sean correctas

Caché de npm desactualizado:

npm cache clean --force
npx @grec0/mcp-planka@latest

Error de certificado SSL (UNABLE_TO_VERIFY_LEAF_SIGNATURE)

Si obtiene errores relacionados con certificados SSL autofirmados o internos:

Error: unable to verify the first certificate
Error: UNABLE_TO_VERIFY_LEAF_SIGNATURE

Solución: Habilitar conexiones inseguras agregando PLANKA_ALLOW_INSECURE: "true" a la configuración:

"env": {
  "PLANKA_BASE_URL": "https://planka-interno.empresa.com",
  "PLANKA_AGENT_EMAIL": "[email protected]",
  "PLANKA_AGENT_PASSWORD": "tu-contraseña",
  "PLANKA_ALLOW_INSECURE": "true"
}

⚠️ ADVERTENCIA DE SEGURIDAD: Solo usar PLANKA_ALLOW_INSECURE=true en entornos internos de confianza. Esta opción desactiva la validación de certificados SSL y no debe usarse para servidores públicos en Internet.

Otros errores comunes

Error de conexión: Verificar que PLANKA_BASE_URL sea correcta y accesible
Error de autenticación: Verificar email y contraseña en las variables de entorno
Timeout: Verificar conectividad de red con el servidor Planka

Variables de Entorno Principales

# Configuración básica
PLANKA_BASE_URL=http://localhost:3000
PLANKA_AGENT_EMAIL=[email protected]
PLANKA_AGENT_PASSWORD=demo

# Opcional: Para certificados SSL autofirmados o internos
PLANKA_ALLOW_INSECURE=true

Configuración de Servidor Planka Local

Si necesita un servidor Planka local para desarrollo:

# Usando Docker Compose
docker-compose up -d

# O usando NPM scripts del proyecto
npm run up

# Acceder a Planka
# URL: http://localhost:3000
# Credenciales por defecto: [email protected] / demo

🚀 Uso

Iniciar el servidor (instalación local)

npm run start

Modo desarrollo

npm run dev

Con inspector MCP

npm run inspector

Scripts Docker (Para Planka local)

# Iniciar contenedores Planka
npm run up

# Detener contenedores
npm run down

# Reiniciar contenedores
npm run restart

📚 Ejemplos de Uso

Gestión de Proyectos

// Listar proyectos
mcp_kanban_project_board_manager({
  action: "get_projects",
  page: 1,
  perPage: 10
})

// Crear tablero
mcp_kanban_project_board_manager({
  action: "create_board",
  projectId: "project_id",
  name: "Mi Nuevo Tablero",
  position: 1
})

Gestión de Tarjetas

// Crear tarjeta con tareas
mcp_kanban_card_manager({
  action: "create_with_tasks",
  listId: "list_id",
  name: "Nueva Funcionalidad",
  description: "Implementar nueva característica",
  tasks: ["Diseño", "Desarrollo", "Testing", "Deploy"],
  comment: "Tarjeta creada automáticamente"
})

// Mover tarjeta entre listas
mcp_kanban_card_manager({
  action: "move",
  id: "card_id",
  listId: "new_list_id",
  position: 0
})

Seguimiento de Tiempo

// Iniciar cronómetro
mcp_kanban_stopwatch({
  action: "start",
  id: "card_id"
})

// Detener cronómetro
mcp_kanban_stopwatch({
  action: "stop",
  id: "card_id"
})

🔧 Solución de Problemas

Error de Conexión con Planka

Si obtiene errores de conexión:

Verificar URL base: Asegúrese que PLANKA_BASE_URL sea correcta
Verificar credenciales: Email y contraseña deben ser válidos
Verificar conectividad: El servidor Planka debe estar ejecutándose

# Probar conectividad manualmente
curl -X POST http://localhost:3000/api/access-tokens \
  -H "Content-Type: application/json" \
  -d '{"emailOrUsername": "[email protected]", "password": "demo"}'

Error NPX "Package not found"

Si NPX no encuentra el paquete:

# Limpiar cache de NPX
npx clear-npx-cache

# O instalar globalmente
npm install -g @grec0/mcp-planka

Problemas de Autenticación

# Verificar variables de entorno
echo $PLANKA_BASE_URL
echo $PLANKA_AGENT_EMAIL
# No mostrar password en logs por seguridad

Error de Configuración MCP

Verificar sintaxis JSON en el archivo de configuración
Reiniciar la aplicación después de cambios
Verificar rutas absolutas si usa instalación local

Variables de Entorno Faltantes

Verificar:

PLANKA_BASE_URL configurada correctamente
PLANKA_AGENT_EMAIL y PLANKA_AGENT_PASSWORD válidos
Servidor Planka accesible desde la red

🧪 Testing

npm test

📖 Compatibilidad

Planka: v1.0.0+
Node.js: >=18.0.0
Sistemas: Windows, Linux, macOS
MCP: Compatible con Claude Desktop y otros clientes MCP

🔐 Seguridad

Autenticación basada en credenciales de Planka
Comunicación a través de API REST estándar
Variables de entorno para credenciales seguras
Sin almacenamiento local de credenciales

🤝 Contribución

Fork el proyecto
Crear branch para feature (git checkout -b feature/nueva-funcionalidad)
Commit cambios (git commit -am 'Add nueva funcionalidad')
Push al branch (git push origin feature/nueva-funcionalidad)
Crear Pull Request

📜 License

Este proyecto está licenciado bajo la Licencia MIT - ver el archivo LICENSE para detalles.

🆘 Support

Issues: GitHub Issues
Documentación: Wiki del Proyecto
Planka: Documentación Oficial de Planka

Planka

MCP Planka Server

🚀 Características

📋 Herramientas Disponibles

mcp_kanban_project_board_manager

mcp_kanban_list_manager

mcp_kanban_card_manager

mcp_kanban_stopwatch

mcp_kanban_label_manager

mcp_kanban_task_manager

mcp_kanban_comment_manager

mcp_kanban_membership_manager

🛠️ Instalación

Instalación General MCP EN LOCAL (NO RECOMENDADO)

⚙️ Configuración

Variables de Entorno

Configuración MCP en Aplicaciones USANDO NPX (RECOMENDADO)

Ubicación del archivo de configuración

Para Claude Desktop (config.json)

Para instalación local

Para entorno de desarrollo

Verificar configuración MCP

🔧 Solución de Problemas

Error: "no server info found"

Error de certificado SSL (UNABLE_TO_VERIFY_LEAF_SIGNATURE)

Otros errores comunes

Variables de Entorno Principales

Configuración de Servidor Planka Local

🚀 Uso

Iniciar el servidor (instalación local)

Modo desarrollo

Con inspector MCP

Scripts Docker (Para Planka local)

📚 Ejemplos de Uso

Gestión de Proyectos

Gestión de Tarjetas

Seguimiento de Tiempo

🔧 Solución de Problemas

Error de Conexión con Planka

Error NPX "Package not found"

Problemas de Autenticación

Error de Configuración MCP

Variables de Entorno Faltantes

🧪 Testing

📖 Compatibilidad

🔐 Seguridad

🤝 Contribución

📜 License

🆘 Support

Be the First to Experience MCP Now

`mcp_kanban_project_board_manager`

`mcp_kanban_list_manager`

`mcp_kanban_card_manager`

`mcp_kanban_stopwatch`

`mcp_kanban_label_manager`

`mcp_kanban_task_manager`

`mcp_kanban_comment_manager`

`mcp_kanban_membership_manager`