Coolify MCP

Servidor MCP para operações da API Coolify.

Documentação

coolify-mcp

Servidor MCP para a API do Coolify - permite fluxos de trabalho completos de deploy, do zero à produção.

coolify-mcp demo

Tem como alvo a API do Coolify v4.3.10. Tipos e esquemas são gerados diretamente da especificação OpenAPI oficial do Coolify, então as entradas das ferramentas sempre correspondem ao que a API realmente aceita.

Recursos

Fluxo de Trabalho Completo de Deploy: Crie projetos, ambientes, servidores e aplicações do zero
5 Tipos de Aplicação: uma ferramenta createApplication cobre git público, GitHub App, Deploy Key, Dockerfile e fontes de Docker Image — além de deploys Docker Compose via createService (desde o Coolify v4.1, deploys compose são serviços)
Gerenciamento de Ambientes: CRUD completo para variáveis de ambiente com mascaramento de segredos
Controle de Deploy: Deploy (opcionalmente aguardando o status final, com cauda de log em caso de falha), iniciar, parar, reiniciar aplicações
Diagnóstico: diagnoseApp encontra uma aplicação por UUID, nome ou domínio e agrega status, deploys recentes, caudas de log de falha, logs de execução e próximas ações sugeridas
Busca na Documentação: searchDocs executa busca de texto completo na documentação oficial do Coolify a partir de um índice local incluído — sem necessidade de rede
Segurança: Proteção contra escrita, redação de segredos e anotações MCP (readOnlyHint/destructiveHint) para que clientes possam aprovar automaticamente leituras e bloquear chamadas destrutivas
Cobertura quase completa da API: bancos de dados (8 engines, backups, envs), serviços, armazenamentos, tarefas agendadas, equipes, previews, servidores, chaves SSH e GitHub Apps
Eficiente em tokens: 65 ferramentas cujas definições custam ~9k tokens de contexto, com validação rigorosa em tempo de execução contra esquemas gerados a partir da especificação OpenAPI do Coolify

Requisitos

Node 18+
Um token de API do Coolify (Configurações > API no seu painel do Coolify)

Instalação

Claude Desktop, um clique: baixe coolify-mcp.mcpb da versão mais recente e arraste-o para Configurações → Extensões. Você será solicitado a fornecer sua URL e token do Coolify — sem instalação do Node, sem edição de JSON.

Via npm:

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

Início Rápido

CLI do 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 do 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

Ou edite ~/.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>" }

Configuração 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"
      }
    }
  }
}

Variáveis de Ambiente

Variável	Padrão	Descrição
`COOLIFY_BASE_URL`	obrigatório	URL da API do Coolify (ex.: `https://coolify.example.com/api/v1`)
`COOLIFY_TOKEN`	obrigatório	Token da API em Configurações do Coolify > API
`COOLIFY_ALLOW_WRITE`	`true`	Habilita operações de escrita (criar, atualizar, excluir, deploy)
`COOLIFY_STRICT_VERSION`	`false`	Falha em caso de incompatibilidade de versão da API
`COOLIFY_MCP_ELICITATION`	`on`	Defina como `off` para pular a confirmação humana em exclusões destrutivas (válvula de escape para clientes que anunciam elicitação, mas não a implementam)
`MCP_TRANSPORT`	`stdio`	Transporte: `stdio`, `http`, `both`
`PORT`	`7331`	Porta HTTP (ao usar transporte http)
`MCP_HTTP_TOKEN`	não definido	Token Bearer exigido em requisições `/mcp` (transporte HTTP). Definir isso também altera o bind padrão para `0.0.0.0`
`MCP_HTTP_HOST`	`127.0.0.1` (`0.0.0.0` com token)	Interface à qual o transporte HTTP faz bind. Vincular além de loopback sem token registra um aviso alto

Deploy do Zero

Com este MCP, você pode implantar uma aplicação do zero:

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

Referência de Ferramentas

Projetos e Ambientes

Ferramenta	Descrição	Escrita
`listProjects`	Listar todos os projetos
`createProject`	Criar um novo projeto	✓
`updateProject`	Atualizar nome/descrição do projeto	✓
`deleteProject`	Excluir um projeto e todos os seus recursos	✓
`listEnvironments`	Listar ambientes em um projeto
`createEnvironment`	Criar um novo ambiente	✓

Servidores e Infraestrutura

Ferramenta	Descrição	Escrita
`listServers`	Listar todos os servidores
`getServer`	Obter detalhes do servidor
`createServer`	Criar um novo servidor	✓
`validateServer`	Validar conexão do servidor
`listPrivateKeys`	Listar chaves privadas SSH
`createPrivateKey`	Criar uma nova chave SSH	✓
`listGithubApps`	Listar GitHub Apps configurados

Aplicações - Leitura

Ferramenta	Descrição
`listApplications`	Listar todas as aplicações (resumidas por padrão)
`getApplication`	Obter detalhes da aplicação (segredos mascarados por padrão)
`getLogs`	Obter logs de execução da aplicação

Aplicações - Criação

Ferramenta	Descrição	Escrita
`createApplication`	Criar uma aplicação; `type` seleciona a fonte: `public`, `private-github-app`, `private-deploy-key`, `dockerfile` ou `dockerimage`. Campos de cauda longa vão em `extra` e são validados por tipo.	✓

Deploys Docker Compose são criados com createService passando docker_compose_raw — desde o Coolify v4.1, eles são serviços, não aplicações.

Aplicações - Gerenciamento

Ferramenta	Descrição	Escrita
`updateApplication`	Atualizar configuração da aplicação	✓
`deleteApplication`	Excluir uma aplicação	✓
`startApplication`	Iniciar uma aplicação	✓
`stopApplication`	Parar uma aplicação	✓
`restartApplication`	Reiniciar uma aplicação	✓

Variáveis de Ambiente

Ferramenta	Descrição	Escrita
`applicationEnvs`	Gerenciar variáveis de ambiente da aplicação: listar (mascaradas por padrão), criar, atualizar, upsert por chave, bulk_update, excluir	✓

Variáveis de ambiente de banco de dados e serviço têm suas próprias ferramentas: databaseEnvs e serviceEnvs.

Deploys

Ferramenta	Descrição	Escrita
`deploy`	Disparar um deploy; `wait: true` faz polling até o status final e retorna uma cauda de log em caso de falha	✓
`diagnoseApp`	Diagnosticar uma aplicação por UUID, nome ou domínio: status, deploys recentes, cauda de log de falha, logs de execução, dicas
`diagnoseServer`	Diagnosticar um servidor por UUID, nome ou IP: detalhamento de status de recursos, domínios, dicas
`listDeployments`	Listar deploys em execução
`getDeployment`	Obter status e logs do deploy
`listAppDeployments`	Listar deploys de uma aplicação
`cancelDeployment`	Cancelar um deploy em execução	✓

Bancos de Dados

Ferramenta	Descrição	Escrita
`listDatabases`	Listar todos os bancos de dados
`getDatabase`	Obter detalhes do banco de dados
`createDatabase`	Criar um banco de dados; `type` seleciona o engine: postgresql, mysql, mariadb, mongodb, redis, keydb, dragonfly, clickhouse	✓
`updateDatabase`	Atualizar configuração do banco de dados	✓
`deleteDatabase`	Excluir um banco de dados (volumes/configs excluídos por padrão)	✓
`controlDatabase`	Iniciar, parar ou reiniciar um banco de dados	✓
`databaseBackups`	Gerenciar agendamentos e execuções de backup (listar/criar/atualizar/excluir/listar_execuções/excluir_execução)	✓
`databaseEnvs`	Gerenciar variáveis de ambiente do banco de dados (listar/criar/atualizar/bulk_update/excluir)	✓

Serviços

Ferramenta	Descrição	Escrita
`listServices`	Listar serviços
`getService`	Obter detalhes do serviço (segredos mascarados por padrão)
`createService`	Criar um serviço de um clique ou deploy Docker Compose	✓
`updateService`	Atualizar um serviço	✓
`deleteService`	Excluir um serviço	✓
`controlService`	Iniciar, parar ou reiniciar um serviço	✓
`serviceEnvs`	Gerenciar variáveis de ambiente do serviço (listar/criar/atualizar/bulk_update/excluir)	✓

Armazenamentos, Tarefas Agendadas e Previews

Ferramenta	Descrição	Escrita
`storages`	Gerenciar volumes persistentes e montagens de arquivos para aplicações, bancos de dados e serviços	✓
`scheduledTasks`	Gerenciar tarefas cron para aplicações e serviços, incluindo histórico de execução	✓
`deletePreview`	Excluir um deploy de preview por id de pull request	✓

Equipes, Servidores e Git

Ferramenta	Descrição	Escrita
`teams`	Listar equipes, obter equipe atual e listar membros
`updateServer`	Atualizar configuração do servidor	✓
`deleteServer`	Excluir um servidor	✓
`getServerResources`	Listar recursos em execução em um servidor
`getServerDomains`	Listar domínios configurados em um servidor
`getPrivateKey`	Obter metadados da chave SSH (material da chave mascarado por padrão)
`updatePrivateKey`	Atualizar uma chave privada SSH	✓
`deletePrivateKey`	Excluir uma chave privada SSH	✓
`getGithubAppRepositories`	Listar repositórios acessíveis a um GitHub App
`getGithubAppBranches`	Listar branches de um repositório

Operações em Lote

Ferramenta	Descrição	Escrita
`getInfrastructureOverview`	Resumo em uma chamada de servidores, projetos, aplicações (detalhamento de status), bancos de dados, serviços e deploys em execução
`restartProjectApps`	Reiniciar todas as aplicações em um projeto ou ambiente (pede confirmação)	✓
`redeployProject`	Disparar um deploy para todas as aplicações em um projeto ou ambiente (pede confirmação)	✓
`stopAllApplications`	Parada de emergência de todas as aplicações em execução, opcionalmente por projeto (pede confirmação, informando o raio de impacto)	✓

Outros

Ferramenta	Descrição
`listResources`	Listar todos os recursos com filtragem
`searchDocs`	Busca de texto completo na documentação oficial do Coolify (índice incluído, sem rede)
`getHealth`	Verificar se a API do Coolify está ativa

Recursos de Segurança

Proteção contra Escrita

Desative todas as operações de escrita:

COOLIFY_ALLOW_WRITE=false

Mascaramento de Segredos

Valores de variáveis de ambiente são mascarados por padrão
Credenciais de banco de dados são redigidas
Use showSecrets: true somente quando necessário

Reforço do Transporte HTTP

O transporte HTTP faz bind em 127.0.0.1 por padrão. Para expô-lo além de loopback, defina MCP_HTTP_TOKEN — toda requisição a /mcp deve então conter Authorization: Bearer <token> (verificado em tempo constante) — e o bind muda para 0.0.0.0 (substituível com MCP_HTTP_HOST). Vincular a um host não-loopback sem token registra um aviso alto: qualquer pessoa que possa alcançar a porta controla sua instância do Coolify.

Confirmação Humana em Exclusões Destrutivas

Em clientes MCP que suportam elicitação (Claude Code, VS Code Copilot), excluir um projeto, aplicação, banco de dados, serviço, servidor ou chave privada pede sua confirmação primeiro, informando o que será perdido. Clientes sem elicitação se comportam exatamente como antes. Uma recusa, cancelamento ou timeout aborta a chamada; defina COOLIFY_MCP_ELICITATION=off para desativar os prompts completamente.

Desenvolvimento

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

Versão Fixada do Coolify

A versão é definida em src/coolify/constants.ts. Para atualizar:

Edite COOLIFY_VERSION em src/coolify/constants.ts
Execute npm run generate

Listagens de Registro

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

Exemplos 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();

Licença

MIT

Coolify MCP

Documentação

coolify-mcp

Recursos

Requisitos

Instalação

Início Rápido

CLI do Claude Code

CLI do OpenAI Codex

Configuração Manual (~/.mcp.json)

Variáveis de Ambiente

Deploy do Zero

Referência de Ferramentas

Projetos e Ambientes

Servidores e Infraestrutura

Aplicações - Leitura

Aplicações - Criação

Aplicações - Gerenciamento

Variáveis de Ambiente

Deploys

Bancos de Dados

Serviços

Armazenamentos, Tarefas Agendadas e Previews

Equipes, Servidores e Git

Operações em Lote

Outros

Recursos de Segurança

Proteção contra Escrita

Mascaramento de Segredos

Reforço do Transporte HTTP

Confirmação Humana em Exclusões Destrutivas

Desenvolvimento

Scripts

Versão Fixada do Coolify

Listagens de Registro

Exemplos de Clientes MCP

Cliente HTTP

Cliente Stdio

Licença

Configuração Manual (`~/.mcp.json`)