CLAUDE_DESKTOP_MCP_SETUP.md

Configuración de Claude Desktop con VibeKanban en Docker

Esta guía explica cómo conectar Claude Desktop con VibeKanban corriendo en un contenedor Docker.

Arquitectura

┌─────────────────────┐     stdio      ┌─────────────────────┐
│   Claude Desktop    │◄──────────────►│  MCP Proxy Script   │
│   (MCP Client)      │                │  (vibekanban-mcp-   │
└─────────────────────┘                │   proxy.sh)         │
                                       └──────────┬──────────┘
                                                  │
                                                  │ docker exec -i
                                                  │
                                       ┌──────────▼──────────┐
                                       │  Docker Container   │
                                       │    (vibekanban)     │
                                       │                     │
                                       │  npx vibe-kanban    │
                                       │      --mcp          │
                                       └─────────────────────┘

Requisitos Previos

1. Docker Desktop instalado y corriendo
2. Claude Desktop instalado
3. VibeKanban corriendo en Docker:

   cd sdd-dev
   docker compose up -d vibekanban

Configuración

Paso 1: Hacer el script ejecutable

chmod +x scripts/vibekanban-mcp-proxy.sh

Paso 2: Obtener la ruta absoluta del script

# En macOS/Linux
realpath scripts/vibekanban-mcp-proxy.sh
# Ejemplo de salida: /Users/tuusuario/sdd-dev/scripts/vibekanban-mcp-proxy.sh

Paso 3: Configurar Claude Desktop

Edita el archivo de configuración de Claude Desktop:

Sistema Operativo	Ubicación del archivo
macOS	~/Library/Application Support/Claude/claude_desktop_config.json
Windows	%APPDATA%\Claude\claude_desktop_config.json
Linux	~/.config/Claude/claude_desktop_config.json

Agrega la siguiente configuración:

{
  "mcpServers": {
    "vibe_kanban": {
      "command": "/ruta/absoluta/a/sdd-dev/scripts/vibekanban-mcp-proxy.sh",
      "args": []
    }
  }
}

Ejemplo para macOS:

{
  "mcpServers": {
    "vibe_kanban": {
      "command": "/Users/tuusuario/sdd-dev/scripts/vibekanban-mcp-proxy.sh",
      "args": []
    }
  }
}

Ejemplo para Windows (usando Git Bash o WSL):

{
  "mcpServers": {
    "vibe_kanban": {
      "command": "C:\\Users\\tuusuario\\sdd-dev\\scripts\\vibekanban-mcp-proxy.sh",
      "args": []
    }
  }
}

Paso 4: Reiniciar Claude Desktop

Cierra completamente Claude Desktop y vuelve a abrirlo.

Paso 5: Verificar la conexión

1. En Claude Desktop, haz clic en el botón "+" en la parte inferior del chat
2. Selecciona "Connectors"
3. Deberías ver "vibe_kanban" en la lista de servidores MCP conectados

Uso

Una vez configurado, puedes usar comandos naturales en Claude Desktop:

Listar proyectos

Lista todos mis proyectos en Vibe Kanban

Crear tareas automáticamente

Necesito construir un sistema de autenticación con:
- Registro de usuarios con validación de email
- Login/logout
- Recuperación de contraseña
- Gestión de sesiones

Luego convierte este plan en tareas en Vibe Kanban.

Iniciar trabajo en una tarea

Inicia trabajo en la tarea "Implementar registro de usuarios" usando OpenCode

Herramientas MCP Disponibles

Una vez conectado, Claude Desktop tendrá acceso a estas herramientas:

Herramienta	Descripción	Parámetros
list_projects	Lista todos los proyectos	Ninguno
list_tasks	Lista tareas de un proyecto	project_id, status (opcional)
create_task	Crea una nueva tarea	project_id, title, description
get_task	Obtiene detalles de una tarea	task_id
update_task	Actualiza una tarea	task_id, title, description, status
delete_task	Elimina una tarea	task_id
start_workspace_session	Inicia trabajo con un agente	task_id, executor, repos
list_repos	Lista repositorios de un proyecto	project_id
get_context	Obtiene contexto del workspace	Ninguno

Executors Soportados

Al usar start_workspace_session, puedes especificar estos agentes:

Executor	Descripción
opencode	OpenCode AI
claude-code	Claude Code
gemini	Gemini CLI
codex	OpenAI Codex
amp	Amp
cursor_agent	Cursor Agent CLI
qwen-code	Qwen Code
copilot	GitHub Copilot
droid	Factory Droid

Solución de Problemas

Error: "Docker no está corriendo"

Asegúrate de que Docker Desktop esté iniciado:

docker info

Error: "El contenedor vibekanban no está corriendo"

Inicia el contenedor:

cd sdd-dev
docker compose up -d vibekanban

Error: "Permission denied" al ejecutar el script

Haz el script ejecutable:

chmod +x scripts/vibekanban-mcp-proxy.sh

Claude Desktop no muestra vibe_kanban en Connectors

1. Verifica que la ruta en claude_desktop_config.json sea correcta y absoluta
2. Verifica que el archivo JSON sea válido (sin errores de sintaxis)
3. Reinicia Claude Desktop completamente (cierra todas las ventanas)

El servidor MCP no responde

Verifica que el contenedor esté saludable:

docker compose ps vibekanban
# Debería mostrar "healthy" en STATUS

Alternativa: Docker MCP Toolkit

Si prefieres usar Docker MCP Toolkit (disponible en Docker Desktop 4.40+), puedes:

1. Abrir Docker Desktop
2. Ir a Settings → Beta Features → Habilitar MCP Toolkit
3. Ir a MCP Toolkit en el sidebar
4. Hacer clic en "Connect" bajo Claude Desktop

Esto configura automáticamente la conexión, pero requiere agregar VibeKanban como un servidor MCP personalizado en el catálogo de Docker.

Notas Importantes

• El servidor MCP de VibeKanban es local-only - solo funciona con aplicaciones instaladas en tu computadora
• El contenedor Docker debe estar corriendo para que la conexión funcione
• Los datos de VibeKanban se persisten en el volumen vibekanban-data