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:

npm install

2. Configurar variables de entorno:

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

3. Compilar:

npm run build

⚙️ Configuración

Variables de Entorno

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": "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:

{
  "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:

{
  "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

{
  "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

{
  "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:

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

2. Variables de entorno faltantes o incorrectas:

"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:

4. 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": "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

# 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:

# 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)

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:

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

# 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:

# 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

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

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 para detalles.

🆘 Support

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