Dokku

Un servidor MCP para gestionar aplicaciones en Dokku, la PaaS de código abierto.

GitHub
9

Documentación

Servidor MCP de Dokku

Servidor de Model Context Protocol (MCP) para Dokku, escrito en Go.

Versión: consulta releases (dokku-mcp --version)

Este servidor expone las capacidades de gestión de Dokku a través del protocolo estandarizado Model Context Protocol (MCP), permitiendo que los Modelos de Lenguaje de Gran Tamaño (LLMs) interactúen con y gestionen una instancia de Dokku.

⚠️ Desarrollo temprano: Este proyecto se encuentra en sus primeras etapas. Se esperan cambios disruptivos y no se recomienda su uso en producción.

MCP Badge

Pruébalo ahora: convierte tu instancia de Dokku en una PaaS gestionable por IA

Sigue la instalación u obtén un binario precompilado para empezar en minutos con cursor, claude-code, goose y todas las herramientas de agentes que soporten mcp.

O make start si ya tienes go instalado localmente.

MCP Inspector Playground

Para una visita rápida al servidor sin configurar un cliente MCP completo, usa el objetivo de make dedicado:

make inspect

Compila el binario (si es necesario), lanza el CLI de MCP Inspector y lo conecta al servidor en modo stdio. Inspector imprime una URL local: ábrela en tu navegador para explorar recursos, prompts y herramientas, o para realizar llamadas ad-hoc. Esta es una excelente manera de validar tu configuración antes de conectar Dokku MCP a Cursor, Claude, otros IDEs o herramientas internas.

Conexión de clientes MCP

El servidor puede usarse con cualquier cliente compatible con MCP.

Añade lo siguiente a tu zed, .cursor/mcp.json, windsurf, claude_desktop_config.json o .mcp.json:

{
  "mcpServers": {
    "dokku": {
      "command": "/home/user/dokku-mcp/build/dokku-mcp",
      "args": [],
      "env": {
        "DOKKU_MCP_SECURITY_BLACKLIST": "destroy,uninstall,remove",
        "DOKKU_MCP_SSH_HOST": "127.0.0.1",
        "DOKKU_MCP_SSH_KEY_PATH": "/home/user/.ssh/id_rsa",
        "DOKKU_MCP_SSH_PORT": "22",
        "DOKKU_MCP_SSH_USER": "dokku"
      }
    }
  }
}

Recuerda reemplazar la ruta command con la ruta absoluta al binario.

Herramientas

Las herramientas están agrupadas por plugin. Los plugins vinculados a un plugin de Dokku (por ejemplo, Let's Encrypt) solo aparecen cuando ese plugin está instalado. Cada herramienta lleva anotaciones MCP (título, solo lectura, destructiva, idempotente), y las herramientas más nuevas devuelven contenido estructurado con un esquema de salida.

ÁreaHerramientas
Aplicacionescreate_app, deploy_app, rollback_app, scale_app, configure_app, get_app_status, restart_app, stop_app, start_app
Desplieguesget_deployment_status, list_deployments
Registrosget_runtime_logs, follow_runtime_logs (en vivo, transmitidos como notificaciones de progreso), get_failed_deploy_logs
Almacenes de datoslist_services, create_service, get_service_info, link_service, unlink_service, get_service_logs, destroy_service (postgres, mysql, mariadb, redis, mongo, rabbitmq, memcached, clickhouse, elasticsearch)
Dominiosget_app_domains, add_app_domain, remove_app_domain, list_global_domains, add_global_domain
HTTPSget_letsencrypt_status, enable_letsencrypt, disable_letsencrypt, set_letsencrypt_email
Accesolist_ssh_keys, add_ssh_key, remove_ssh_key, get_registry_report, registry_login, registry_logout
Servidorget_server_logs (opt-in con expose_server_logs)

Los recursos incluyen dokku://onboarding/quickstart (empieza aquí), dokku://onboarding/capabilities, dokku://onboarding/intent-map, dokku://core/server/info y dokku://app/{name}/logs. El prompt app_doctor guía el diagnóstico de una aplicación.

Los despliegues son asíncronos: deploy_app devuelve un deployment_id tan pronto como el código está sincronizado, y get_deployment_status informa el resultado de la compilación y el final del registro de compilación.

Seguridad

El servidor ejecuta comandos de Dokku a través de SSH con la clave configurada, así que trátalo como esa clave.

  • Seguridad de argumentos. El comando SSH de Dokku divide los argumentos por palabras, por lo que cada argumento se verifica contra un conjunto de caracteres seguro para shell. Los valores de formato libre (variables de entorno, contraseñas de registro, claves públicas SSH) se envían codificados en base64 o a través de stdin, nunca interpolados en la línea de comandos.
  • Lista de permitidos / bloqueados. security.allowlist restringe el servidor a comandos coincidentes ("apps:", "config:*", "logs", ...); security.blacklist bloquea comandos que contengan un patrón (destroy, uninstall, ...). Ambos pueden configurarse con DOKKU_MCP_SECURITY_ALLOWLIST / DOKKU_MCP_SECURITY_BLACKLIST como listas separadas por comas.
  • Secretos en la salida. Las URL de conexión y contraseñas de los almacenes de datos se enmascaran en los resultados de las herramientas.
  • Barreras de protección. destroy_service requiere que el nombre del servicio se repita; add_ssh_key rechaza nombres que contengan admin (que Dokku permite para añadir más claves) a menos que allow_admin esté configurado.
  • Transporte remoto. El transporte SSE aún no tiene autenticación. Solo expónlo en una red de confianza o detrás de un proxy autenticado.

Hoja de ruta

Envía un issue para proponer una re-priorización

SIGUIENTE

  • Transporte HTTP transmisible y autenticación: reemplazar SSE, añadir soporte de bearer token / OAuth y ámbitos por token.
  • Confirmación para herramientas destructivas: usar la elicitación de MCP para operaciones de destroy/stop/remove.
  • Distribución: imagen Docker, Homebrew tap y un plugin de Dokku que ejecute el servidor en el host.

IDEAS

  • Historial de versiones: mantener un registro de despliegue duradero para que los rollbacks puedan elegir entre versiones anteriores.
  • Más plugins de Dokku: puertos, checks, cron, montajes de almacenamiento.

Integraciones de Dokku

  • Implementadas: apps:list, apps:info, apps:create, apps:exists, apps:report, config:show, config:set --encoded, ps:scale, ps:report, ps:rebuild, ps:restart, ps:stop, ps:start, git:sync, logs (incluyendo seguimiento de -t), logs:failed, domains:report, domains:add, domains:remove, domains:add-global, letsencrypt:*, <datastore>:create/info/list/link/unlink/links/logs/destroy, ssh-keys:list/add/remove, registry:login/logout/report, plugin:list, version, proxy:report, scheduler:report, git:report.
  • Faltantes/parciales: ports:*, checks:*, storage:*, cron:*, copias de seguridad de almacenes de datos.

Contribuye: reporta problemas o propone funciones

Abre un issue o lee Contribuir.

🪿 Obtén ayuda de Goose AI en los issues

¿Necesitas ayuda con el proyecto dokku-mcp? Goose AI está disponible para ayudarte. Simplemente etiqueta tus issues o pull requests de GitHub con la etiqueta :goose, y Goose AI será notificado automáticamente para ayudar con desarrollo, depuración, implementación de funciones y otras tareas relacionadas con el proyecto.

Ejemplo de Goose AI en acción Otro ejemplo

Tabla de contenidos

Instalación

Binarios precompilados

Descarga la última versión para tu plataforma:

# Linux (amd64; also available: arm64, arm)
curl -L -o dokku-mcp https://github.com/dokku-mcp/dokku-mcp/releases/latest/download/dokku-mcp-linux-amd64
chmod +x dokku-mcp
sudo mv dokku-mcp /usr/local/bin/

# macOS (amd64; also available: arm64)
curl -L -o dokku-mcp https://github.com/dokku-mcp/dokku-mcp/releases/latest/download/dokku-mcp-darwin-amd64
chmod +x dokku-mcp
sudo mv dokku-mcp /usr/local/bin/

Los archivos comprimidos (dokku-mcp-<os>-<arch>.tar.gz) también se publican con cada versión.

Paquete MCP

Cada versión estable también incluye dokku-mcp.mcpb, un Paquete MCP para macOS y Linux que los clientes MCP como Claude Desktop instalan en un solo paso, solicitando el host de Dokku, usuario SSH, puerto y clave. El mismo paquete se publica en el Registro oficial de MCP como io.github.dokku-MCP/dokku-mcp.

Verificar la instalación

dokku-mcp --version

Compilar desde el código fuente

Si prefieres compilar desde el código fuente:

  1. Requisitos previos:

    • Go (versión 1.26 o posterior)

  2. Clonar y compilar:

    git clone https://github.com/dokku-mcp/dokku-mcp.git
cd dokku-mcp
make build

Configuración

El servidor se puede configurar de dos maneras: usando un archivo config.yaml o mediante variables de entorno.

Archivo de configuración

Crea un archivo de configuración en una de las siguientes ubicaciones:

  • A nivel de sistema: /etc/dokku-mcp/config.yaml
  • Específico de usuario: ~/.dokku-mcp/config.yaml
  • Local: config.yaml en el mismo directorio que el binario.

Aquí tienes un ejemplo mínimo de config.yaml:

ssh:
  host: "your-dokku-host.com"
  user: "dokku"
  # key_path: "/path/to/your/ssh/private/key" # Optional, uses ssh-agent if empty

log_level: "info"

Para una lista completa de opciones disponibles, consulta el archivo config.yaml.example.

Variables de entorno

Toda la configuración se puede sobrescribir con variables de entorno con prefijo DOKKU_MCP_. Las claves anidadas usan guiones bajos (ssh.host → DOKKU_MCP_SSH_HOST) y las listas están separadas por comas. Por ejemplo:

export DOKKU_MCP_SSH_HOST="your-dokku-host.com"
export DOKKU_MCP_SSH_USER="dokku"
export DOKKU_MCP_LOG_LEVEL="debug"
export DOKKU_MCP_SECURITY_ALLOWLIST="apps:,config:,ps:,git:sync,logs,version"

Ejecutar el servidor

Una vez configurado, puedes ejecutar el servidor:

dokku-mcp

El servidor se iniciará y estará listo para aceptar conexiones de un cliente MCP.

Desarrollo local de Dokku

Para desarrollo y pruebas sin necesidad de una instancia remota de Dokku, puedes ejecutar un servidor local de Dokku usando Docker.

Requisitos previos:

  1. Configurar el contenedor local de Dokku:

    Este comando descargará las imágenes Docker necesarias y configurará la instancia local de Dokku. Solo necesita ejecutarse una vez.

    make setup-dokku

make dokku-start

  2. Detener el contenedor local de Dokku:

    make dokku-stop

Cuando el contenedor local de Dokku está en ejecución, el servidor MCP (con la configuración predeterminada) debería poder conectarse a él. Puedes ejecutar pruebas de integración contra esta instancia local.

Modos de transporte

El servidor admite dos modos de transporte para clientes:

  • stdio (predeterminado): Entrada/salida estándar para comunicación directa de procesos.
  • sse (Server-Sent Events): Transporte basado en HTTP para clientes web. 
    DOKKU_MCP_TRANSPORT_TYPE=sse dokku-mcp

Configuración de CORS

Para el transporte SSE, CORS se maneja de forma predeterminada con Access-Control-Allow-Origin: *. Para despliegues remotos, puedes habilitar middleware CORS personalizado:

transport:
  type: sse
  cors:
    enabled: true
    allowed_origins:
      - "https://app.example.com"
      - "*.example.com"

Consulta docs/CORS.md para opciones de configuración detalladas y mejores prácticas de seguridad.

Desarrollo

Esta sección es para desarrolladores que quieran contribuir al proyecto o modificar el código fuente.

Configuración de desarrollo

  1. Requisitos previos:

    • Go (versión 1.26 o posterior)
    • Docker y Docker Compose
    • Make

  2. Clonar el repositorio:

    git clone https://github.com/dokku-mcp/dokku-mcp.git
cd dokku-mcp

  3. Instalar herramientas de desarrollo:

    Este comando instala todas las herramientas Go necesarias para desarrollo, linting y pruebas.

    make install-tools

  4. Configurar el entorno de desarrollo:

    Este comando configura los hooks de Git para garantizar la calidad del código antes de los commits.

    make setup-dev

  5. Compilar y ejecutar desde el código fuente:

    # This command builds the binary and starts the server.
make start

Comandos de Makefile

El proyecto usa un Makefile para automatizar tareas comunes.

  • make help: Muestra todos los comandos disponibles.
  • make check: Ejecuta todas las verificaciones de calidad de código (linting, formato, complejidad).
  • make build: Compila el binario del servidor.
  • make clean: Limpia los artefactos de compilación.

Pruebas

  • Ejecutar todas las pruebas:

    make test

    Esto ejecuta todas las pruebas unitarias y de integración y genera un informe de cobertura HTML en coverage.html.

  • Ejecutar pruebas de integración contra Dokku local: Asegúrate de que tu contenedor local de Dokku esté en ejecución (make dokku-start).

    make test-integration-local

Arquitectura

El servidor sigue los principios de Domain-Driven Design (DDD), con una separación clara entre:

  • Capa de dominio (internal/domain): Lógica de negocio central, entidades e interfaces de repositorio.
  • Capa de aplicación (internal/application): Orquestación y coordinación de casos de uso.
  • Capa de infraestructura (internal/infrastructure): Implementaciones de interfaces, como el cliente de Dokku, bases de datos y servicios externos.

Cuenta con una arquitectura basada en plugins ubicada en internal/server-plugins, donde cada plugin encapsula un conjunto específico de funciones de Dokku (por ejemplo, app, core, deployment).

Para más detalles, consulta la documentación en el directorio docs/.

Estructura del proyecto

dokku-mcp/
├── cmd/                    # Entry points for the application
│   └── server/             # Server main command
├── internal/               # Private application code
│   ├── server/             # MCP server and adapter
│   ├── server-plugin/      # Plugin system infrastructure
│   ├── server-plugins/     # Actual plugin implementations (app, core, etc.)
│   ├── dokku-api/          # Dokku CLI client and API
│   └── shared/             # Shared domain types and services
├── pkg/                    # Reusable packages (config, logger, etc.)
├── docs/                   # Project documentation
└── scripts/                # Helper scripts

Contribuir

¡Las contribuciones son bienvenidas! Consulta Contribuir para obtener una guía detallada sobre cómo contribuir.

Licencia

Este proyecto está bajo la Licencia Apache 2.0: consulta el archivo LICENSE para más detalles. Copyright [Alex Galey]

Licenciado bajo la Licencia Apache, Versión 2.0 (la "Licencia"); no puede usar este archivo excepto en cumplimiento con la Licencia. Puede obtener una copia de la Licencia en

http://www.apache.org/licenses/LICENSE-2.0

Salvo que lo exija la ley aplicable o se acuerde por escrito, el software distribuido bajo la Licencia se distribuye "TAL CUAL", SIN GARANTÍAS NI CONDICIONES DE NINGÚN TIPO, ya sean expresas o implícitas. Consulte la Licencia para conocer los permisos y limitaciones específicos bajo la Licencia.