Planka MCP Server

# 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) 1. **Instalar dependencias**: ```bash npm install ``` 2. **Configurar variables de entorno**: ```bash cp config.example.env .env # Editar .env con la configuración de su servidor Planka ``` 3. **Compilar**: ```bash 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):** ```json { "mcpServers": { "planka": { "command": "npx", "args": ["@grec0/mcp-planka@latest"], "env": { "PLANKA_BASE_URL": "http://localhost:3000", "PLANKA_AGENT_EMAIL": "demo@demo.demo", "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:** ```json { "mcpServers": { "planka": { "command": "npx", "args": ["@grec0/mcp-planka@latest"], "env": { "PLANKA_BASE_URL": "https://tu-planka-server.com", "PLANKA_AGENT_EMAIL": "tu-email@ejemplo.com", "PLANKA_AGENT_PASSWORD": "tu-contraseña" } } } } ``` **Para servidor Planka con certificado SSL autofirmado o interno:** ```json { "mcpServers": { "planka": { "command": "npx", "args": ["@grec0/mcp-planka@latest"], "env": { "PLANKA_BASE_URL": "https://planka-interno.empresa.com", "PLANKA_AGENT_EMAIL": "tu-email@ejemplo.com", "PLANKA_AGENT_PASSWORD": "tu-contraseña", "PLANKA_ALLOW_INSECURE": "true" } } } } ``` #### Para instalación local ```json { "mcpServers": { "planka": { "command": "node", "args": ["C:/ruta/a/kanban-mcp/dist/index.js"], "env": { "PLANKA_BASE_URL": "http://localhost:3000", "PLANKA_AGENT_EMAIL": "demo@demo.demo", "PLANKA_AGENT_PASSWORD": "demo" } } } } ``` #### Para entorno de desarrollo ```json { "mcpServers": { "planka": { "command": "npm", "args": ["run", "dev"], "cwd": "C:/ruta/a/kanban-mcp", "env": { "PLANKA_BASE_URL": "http://localhost:3000", "PLANKA_AGENT_EMAIL": "demo@demo.demo", "PLANKA_AGENT_PASSWORD": "demo" } } } } ``` ### Verificar configuración MCP Después de configurar el MCP, puedes verificar que funciona correctamente: 1. **Reiniciar la aplicación** (Claude Desktop, etc.) 2. **Probar operación básica**: ``` mcp_kanban_project_board_manager(action: "get_projects", page: 1, perPage: 10) ``` 3. **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: 1. **Falta el `@latest` en la configuración**: ```json // ❌ INCORRECTO "args": ["@grec0/mcp-planka"] // ✅ CORRECTO "args": ["@grec0/mcp-planka@latest"] ``` 2. **Variables de entorno faltantes o incorrectas**: ```json "env": { "PLANKA_BASE_URL": "http://localhost:3000", "PLANKA_AGENT_EMAIL": "demo@demo.demo", "PLANKA_AGENT_PASSWORD": "demo" } ``` 3. **El servidor Planka no está ejecutándose**: - Verificar que Planka esté en `http://localhost:3000` - Verificar que las credenciales sean correctas 4. **Caché de npm desactualizado**: ```bash 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: ```json "env": { "PLANKA_BASE_URL": "https://planka-interno.empresa.com", "PLANKA_AGENT_EMAIL": "tu-email@ejemplo.com", "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 ```bash # Configuración básica PLANKA_BASE_URL=http://localhost:3000 PLANKA_AGENT_EMAIL=demo@demo.demo 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: ```bash # 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: demo@demo.demo / demo ``` ## 🚀 Uso ### Iniciar el servidor (instalación local) ```bash npm run start ``` ### Modo desarrollo ```bash npm run dev ``` ### Con inspector MCP ```bash npm run inspector ``` ### Scripts Docker (Para Planka local) ```bash # Iniciar contenedores Planka npm run up # Detener contenedores npm run down # Reiniciar contenedores npm run restart ``` ## 📚 Ejemplos de Uso ### Gestión de Proyectos ```javascript // 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 ```javascript // 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 ```javascript // 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: 1. **Verificar URL base**: Asegúrese que `PLANKA_BASE_URL` sea correcta 2. **Verificar credenciales**: Email y contraseña deben ser válidos 3. **Verificar conectividad**: El servidor Planka debe estar ejecutándose ```bash # Probar conectividad manualmente curl -X POST http://localhost:3000/api/access-tokens \ -H "Content-Type: application/json" \ -d '{"emailOrUsername": "demo@demo.demo", "password": "demo"}' ``` ### Error NPX "Package not found" Si NPX no encuentra el paquete: ```bash # Limpiar cache de NPX npx clear-npx-cache # O instalar globalmente npm install -g @grec0/mcp-planka ``` ### Problemas de Autenticación ```bash # Verificar variables de entorno echo $PLANKA_BASE_URL echo $PLANKA_AGENT_EMAIL # No mostrar password en logs por seguridad ``` ### Error de Configuración MCP 1. **Verificar sintaxis JSON** en el archivo de configuración 2. **Reiniciar la aplicación** después de cambios 3. **Verificar rutas absolutas** si usa instalación local ### Variables de Entorno Faltantes Verificar: 1. `PLANKA_BASE_URL` configurada correctamente 2. `PLANKA_AGENT_EMAIL` y `PLANKA_AGENT_PASSWORD` válidos 3. Servidor Planka accesible desde la red ## 🧪 Testing ```bash 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 1. Fork el proyecto 2. Crear branch para feature (`git checkout -b feature/nueva-funcionalidad`) 3. Commit cambios (`git commit -am 'Add nueva funcionalidad'`) 4. Push al branch (`git push origin feature/nueva-funcionalidad`) 5. Crear Pull Request ## 📜 License Este proyecto está licenciado bajo la Licencia MIT - ver el archivo [LICENSE](LICENSE) para detalles. ## 🆘 Support - **Issues**: [GitHub Issues](https://github.com/grec0/mcp-planka/issues) - **Documentación**: [Wiki del Proyecto](https://github.com/grec0/mcp-planka/wiki) - **Planka**: [Documentación Oficial de Planka](https://docs.planka.cloud/)