Coolify MCP

Servidor MCP para operaciones de la API de Coolify.

Documentación

coolify-mcp

Servidor MCP para la API de Coolify: permite flujos de trabajo de despliegue completos, desde cero hasta producción.

coolify-mcp demo

Apunta a la API de Coolify v4.3.10. Los tipos y esquemas se generan directamente desde la especificación OpenAPI oficial de Coolify, por lo que las entradas de las herramientas siempre coinciden con lo que la API realmente acepta.

Características

Flujo de trabajo de despliegue completo: crea proyectos, entornos, servidores y aplicaciones desde cero
5 tipos de aplicaciones: una herramienta createApplication cubre git público, GitHub App, Deploy Key, Dockerfile y fuentes de imágenes Docker, además de despliegues de Docker Compose mediante createService (desde Coolify v4.1, los despliegues de compose son servicios)
Gestión de entornos: CRUD completo para variables de entorno con enmascaramiento de secretos
Control de despliegues: desplegar (opcionalmente esperando el estado terminal, con un seguimiento de registros en caso de fallo), iniciar, detener, reiniciar aplicaciones
Diagnóstico: diagnoseApp encuentra una aplicación por UUID, nombre o dominio y agrega estado, despliegues recientes, seguimiento de registros de fallos, registros de ejecución y acciones sugeridas a continuación
Búsqueda en documentación: searchDocs realiza búsqueda de texto completo en la documentación oficial de Coolify desde un índice local incluido, sin necesidad de red
Seguridad: protección de escritura, redacción de secretos y anotaciones MCP (readOnlyHint/destructiveHint) para que los clientes puedan aprobar automáticamente lecturas y controlar llamadas destructivas
Cobertura casi completa de la API: bases de datos (8 motores, copias de seguridad, entornos), servicios, almacenamientos, tareas programadas, equipos, vistas previas, servidores, claves SSH y GitHub Apps
Eficiente en tokens: 65 herramientas cuyas definiciones cuestan ~9k tokens de contexto, con validación estricta en tiempo de ejecución contra esquemas generados desde la especificación OpenAPI de Coolify

Requisitos

Node 18+
Un token de API de Coolify (Configuración > API en tu panel de Coolify)

Instalación

Claude Desktop, un clic: descarga coolify-mcp.mcpb desde la última versión y arrástralo a Configuración → Extensiones. Se te pedirá tu URL y token de Coolify: sin instalación de Node, sin editar JSON.

Vía npm:

npm install -g @fndchagas/coolify-mcp
# or
npx -y @fndchagas/coolify-mcp

Inicio rápido

CLI de Claude Code

claude mcp add coolify \
  --env COOLIFY_BASE_URL="https://coolify.example.com/api/v1" \
  --env COOLIFY_TOKEN="<token>" \
  -- npx -y @fndchagas/coolify-mcp

CLI de OpenAI Codex

codex mcp add coolify \
  --env COOLIFY_BASE_URL="https://coolify.example.com/api/v1" \
  --env COOLIFY_TOKEN="<token>" \
  -- npx -y @fndchagas/coolify-mcp

O edita ~/.codex/config.toml:

[mcp_servers.coolify]
command = "npx"
args = ["-y", "@fndchagas/coolify-mcp"]
env = { COOLIFY_BASE_URL = "https://coolify.example.com/api/v1", COOLIFY_TOKEN = "<token>" }

Configuración manual (`~/.mcp.json`)

{
  "mcpServers": {
    "coolify": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@fndchagas/coolify-mcp"],
      "env": {
        "COOLIFY_BASE_URL": "https://coolify.example.com/api/v1",
        "COOLIFY_TOKEN": "<token>",
        "COOLIFY_ALLOW_WRITE": "true"
      }
    }
  }
}

Variables de entorno

Variable	Predeterminado	Descripción
`COOLIFY_BASE_URL`	requerido	URL de la API de Coolify (p. ej., `https://coolify.example.com/api/v1`)
`COOLIFY_TOKEN`	requerido	Token de API desde Configuración > API de Coolify
`COOLIFY_ALLOW_WRITE`	`true`	Habilita operaciones de escritura (crear, actualizar, eliminar, desplegar)
`COOLIFY_STRICT_VERSION`	`false`	Fallar en caso de discrepancia de versión de API
`COOLIFY_MCP_ELICITATION`	`on`	Establecer en `off` para omitir la confirmación humana en eliminaciones destructivas (vía de escape para clientes que anuncian elicitación pero no la implementan)
`MCP_TRANSPORT`	`stdio`	Transporte: `stdio`, `http`, `both`
`PORT`	`7331`	Puerto HTTP (cuando se usa transporte http)
`MCP_HTTP_TOKEN`	sin establecer	Token Bearer requerido en solicitudes `/mcp` (transporte HTTP). Configurarlo también cambia el enlace predeterminado a `0.0.0.0`
`MCP_HTTP_HOST`	`127.0.0.1` (`0.0.0.0` con token)	Interfaz a la que se enlaza el transporte HTTP. Enlazar más allá de loopback sin token registra una advertencia fuerte

Desplegar desde cero

Con este MCP, puedes desplegar una aplicación desde cero:

1. listProjects / createProject       → Get or create a project
2. listEnvironments / createEnvironment → Get or create an environment
3. listServers / createServer         → Get or create a server
4. listPrivateKeys / createPrivateKey → Get or create SSH keys (if needed)
5. createApplication (type: public)   → Create the application
6. applicationEnvs (action: upsert)   → Configure environment variables
7. deploy                             → Trigger deployment

Referencia de herramientas

Proyectos y entornos

Herramienta	Descripción	Escritura
`listProjects`	Listar todos los proyectos
`createProject`	Crear un nuevo proyecto	✓
`updateProject`	Actualizar nombre/descripción del proyecto	✓
`deleteProject`	Eliminar un proyecto y todos sus recursos	✓
`listEnvironments`	Listar entornos en un proyecto
`createEnvironment`	Crear un nuevo entorno	✓

Servidores e infraestructura

Herramienta	Descripción	Escritura
`listServers`	Listar todos los servidores
`getServer`	Obtener detalles del servidor
`createServer`	Crear un nuevo servidor	✓
`validateServer`	Validar conexión del servidor
`listPrivateKeys`	Listar claves privadas SSH
`createPrivateKey`	Crear una nueva clave SSH	✓
`listGithubApps`	Listar GitHub Apps configuradas

Aplicaciones - Lectura

Herramienta	Descripción
`listApplications`	Listar todas las aplicaciones (resumidas por defecto)
`getApplication`	Obtener detalles de la aplicación (secretos enmascarados por defecto)
`getLogs`	Obtener registros de ejecución de la aplicación

Aplicaciones - Crear

Herramienta	Descripción	Escritura
`createApplication`	Crear una aplicación; `type` selecciona la fuente: `public`, `private-github-app`, `private-deploy-key`, `dockerfile` o `dockerimage`. Los campos de cola larga van en `extra` y se validan por tipo.	✓

Los despliegues de Docker Compose se crean con createService pasando docker_compose_raw: desde Coolify v4.1 son servicios, no aplicaciones.

Aplicaciones - Gestionar

Herramienta	Descripción	Escritura
`updateApplication`	Actualizar configuración de la aplicación	✓
`deleteApplication`	Eliminar una aplicación	✓
`startApplication`	Iniciar una aplicación	✓
`stopApplication`	Detener una aplicación	✓
`restartApplication`	Reiniciar una aplicación	✓

Variables de entorno

Herramienta	Descripción	Escritura
`applicationEnvs`	Gestionar variables de entorno de la aplicación: listar (enmascaradas por defecto), crear, actualizar, upsert por clave, actualización masiva, eliminar	✓

Las variables de entorno de bases de datos y servicios tienen sus propias herramientas: databaseEnvs y serviceEnvs.

Despliegues

Herramienta	Descripción	Escritura
`deploy`	Activar un despliegue; `wait: true` sondea hasta el estado terminal y devuelve un seguimiento de registros en caso de fallo	✓
`diagnoseApp`	Diagnosticar una aplicación por UUID, nombre o dominio: estado, despliegues recientes, seguimiento de registros de fallos, registros de ejecución, sugerencias
`diagnoseServer`	Diagnosticar un servidor por UUID, nombre o IP: desglose de estado de recursos, dominios, sugerencias
`listDeployments`	Listar despliegues en ejecución
`getDeployment`	Obtener estado y registros del despliegue
`listAppDeployments`	Listar despliegues de una aplicación
`cancelDeployment`	Cancelar un despliegue en ejecución	✓

Bases de datos

Herramienta	Descripción	Escritura
`listDatabases`	Listar todas las bases de datos
`getDatabase`	Obtener detalles de la base de datos
`createDatabase`	Crear una base de datos; `type` selecciona el motor: postgresql, mysql, mariadb, mongodb, redis, keydb, dragonfly, clickhouse	✓
`updateDatabase`	Actualizar configuración de la base de datos	✓
`deleteDatabase`	Eliminar una base de datos (volúmenes/configuraciones eliminados por defecto)	✓
`controlDatabase`	Iniciar, detener o reiniciar una base de datos	✓
`databaseBackups`	Gestionar programaciones y ejecuciones de copias de seguridad (listar/crear/actualizar/eliminar/listar_ejecuciones/eliminar_ejecución)	✓
`databaseEnvs`	Gestionar variables de entorno de la base de datos (listar/crear/actualizar/actualización masiva/eliminar)	✓

Servicios

Herramienta	Descripción	Escritura
`listServices`	Listar servicios
`getService`	Obtener detalles del servicio (secretos enmascarados por defecto)
`createService`	Crear un servicio de un clic o despliegue de Docker Compose	✓
`updateService`	Actualizar un servicio	✓
`deleteService`	Eliminar un servicio	✓
`controlService`	Iniciar, detener o reiniciar un servicio	✓
`serviceEnvs`	Gestionar variables de entorno del servicio (listar/crear/actualizar/actualización masiva/eliminar)	✓

Almacenamientos, tareas programadas y vistas previas

Herramienta	Descripción	Escritura
`storages`	Gestionar volúmenes persistentes y montajes de archivos para aplicaciones, bases de datos y servicios	✓
`scheduledTasks`	Gestionar tareas cron para aplicaciones y servicios, incluido el historial de ejecuciones	✓
`deletePreview`	Eliminar un despliegue de vista previa por ID de solicitud de extracción	✓

Equipos, servidores y Git

Herramienta	Descripción	Escritura
`teams`	Listar equipos, obtener el equipo actual y listar miembros
`updateServer`	Actualizar configuración del servidor	✓
`deleteServer`	Eliminar un servidor	✓
`getServerResources`	Listar recursos que se ejecutan en un servidor
`getServerDomains`	Listar dominios configurados en un servidor
`getPrivateKey`	Obtener metadatos de la clave SSH (material de clave enmascarado por defecto)
`updatePrivateKey`	Actualizar una clave privada SSH	✓
`deletePrivateKey`	Eliminar una clave privada SSH	✓
`getGithubAppRepositories`	Listar repositorios accesibles para una GitHub App
`getGithubAppBranches`	Listar ramas de un repositorio

Operaciones por lotes

Herramienta	Descripción	Escritura
`getInfrastructureOverview`	Resumen en una llamada de servidores, proyectos, aplicaciones (desglose de estado), bases de datos, servicios y despliegues en ejecución
`restartProjectApps`	Reiniciar cada aplicación en un proyecto o entorno (pide confirmación)	✓
`redeployProject`	Activar un despliegue para cada aplicación en un proyecto o entorno (pide confirmación)	✓
`stopAllApplications`	Detención de emergencia de todas las aplicaciones en ejecución, opcionalmente por proyecto (pide confirmación, indicando el radio de impacto)	✓

Otros

Herramienta	Descripción
`listResources`	Listar todos los recursos con filtrado
`searchDocs`	Búsqueda de texto completo en la documentación oficial de Coolify (índice incluido, sin red)
`getHealth`	Verificar que la API de Coolify esté activa

Características de seguridad

Protección de escritura

Deshabilitar todas las operaciones de escritura:

COOLIFY_ALLOW_WRITE=false

Enmascaramiento de secretos

Los valores de variables de entorno se enmascaran por defecto
Las credenciales de bases de datos se redactan
Usa showSecrets: true solo cuando sea necesario

Refuerzo del transporte HTTP

El transporte HTTP se enlaza a 127.0.0.1 por defecto. Para exponerlo más allá de loopback, establece MCP_HTTP_TOKEN: cada solicitud a /mcp debe entonces llevar Authorization: Bearer <token> (verificado en tiempo constante), y el enlace cambia a 0.0.0.0 (anulable con MCP_HTTP_HOST). Enlazar a un host que no sea loopback sin token registra una advertencia fuerte: cualquiera que pueda alcanzar el puerto controla tu instancia de Coolify.

Confirmación humana en eliminaciones destructivas

En clientes MCP que admiten elicitación (Claude Code, VS Code Copilot), eliminar un proyecto, aplicación, base de datos, servicio, servidor o clave privada te pide a ti confirmar primero, indicando qué se perderá. Los clientes sin elicitación se comportan exactamente como antes. Un rechazo, cancelación o tiempo de espera aborta la llamada; establece COOLIFY_MCP_ELICITATION=off para deshabilitar los avisos por completo.

Desarrollo

git clone https://github.com/frndchagas/coolify-mcp.git
cd coolify-mcp
npm install
npm run dev

Scripts

npm run dev            # Run in development mode
npm run build          # Build TypeScript
npm run generate       # Fetch the pinned OpenAPI spec and regenerate types

Versión fijada de Coolify

La versión se define en src/coolify/constants.ts. Para actualizar:

Edita COOLIFY_VERSION en src/coolify/constants.ts
Ejecuta npm run generate

Listados de registro

Registro MCP: io.github.frndchagas/coolify-mcp

Ejemplos de clientes MCP

Cliente HTTP

import { Client } from '@modelcontextprotocol/sdk/client/index.js';
import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js';

const client = new Client({ name: 'coolify-client', version: '1.0.0' });
const transport = new StreamableHTTPClientTransport(
  new URL('http://localhost:7331/mcp')
);

await client.connect(transport);

// List all applications
const apps = await client.callTool({
  name: 'listApplications',
  arguments: {},
});
console.log(apps.structuredContent);

// Deploy an application
const deploy = await client.callTool({
  name: 'deploy',
  arguments: { uuid: 'your-app-uuid' },
});
console.log(deploy.structuredContent);

await client.close();

Cliente Stdio

import { Client } from '@modelcontextprotocol/sdk/client/index.js';
import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';

const client = new Client({ name: 'coolify-client', version: '1.0.0' });
const transport = new StdioClientTransport({
  command: 'npx',
  args: ['-y', '@fndchagas/coolify-mcp'],
  env: {
    COOLIFY_BASE_URL: 'https://coolify.example.com/api/v1',
    COOLIFY_TOKEN: '<token>',
  },
});

await client.connect(transport);

const result = await client.callTool({
  name: 'getApplication',
  arguments: { uuid: 'your-app-uuid' },
});
console.log(result.structuredContent);

await client.close();

Licencia

MIT

Coolify MCP

Documentación

coolify-mcp

Características

Requisitos

Instalación

Inicio rápido

CLI de Claude Code

CLI de OpenAI Codex

Configuración manual (~/.mcp.json)

Variables de entorno

Desplegar desde cero

Referencia de herramientas

Proyectos y entornos

Servidores e infraestructura

Aplicaciones - Lectura

Aplicaciones - Crear

Aplicaciones - Gestionar

Variables de entorno

Despliegues

Bases de datos

Servicios

Almacenamientos, tareas programadas y vistas previas

Equipos, servidores y Git

Operaciones por lotes

Otros

Características de seguridad

Protección de escritura

Enmascaramiento de secretos

Refuerzo del transporte HTTP

Confirmación humana en eliminaciones destructivas

Desarrollo

Scripts

Versión fijada de Coolify

Listados de registro

Ejemplos de clientes MCP

Cliente HTTP

Cliente Stdio

Licencia

Configuración manual (`~/.mcp.json`)