Coolify MCP

Servidor MCP para operações da API Coolify.

Documentação

coolify-mcp

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

coolify-mcp demo

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

Recursos

Fluxo de implantação completo: Crie projetos, ambientes, servidores e aplicativos do zero
5 tipos de aplicativos: uma ferramenta createApplication cobre fontes de git público, GitHub App, Deploy Key, Dockerfile e Docker Image — além de implantações Docker Compose via createService (desde o Coolify v4.1, implantações compose são serviços)
Gerenciamento de ambientes: CRUD completo para variáveis de ambiente com mascaramento de segredos
Controle de implantação: Implante (opcionalmente aguardando o status final, com cauda de log em caso de falha), inicie, pare, reinicie aplicativos
Diagnóstico: diagnoseApp encontra um aplicativo por UUID, nome ou domínio e agrega status, implantações recentes, caudas de log de falhas, logs de execução e próximas ações sugeridas
Pesquisa de documentação: searchDocs realiza pesquisa 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, ocultação de segredos e anotações MCP (readOnlyHint/destructiveHint) para que clientes possam aprovar automaticamente leituras e proteger chamadas destrutivas
Cobertura quase completa da API: bancos de dados (8 mecanismos, backups, ambientes), serviços, armazenamentos, tarefas agendadas, equipes, previews, servidores, chaves SSH e GitHub Apps
Eficiente em tokens: 65 ferramentas cujas definições custam cerca de 9 mil 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 o coolify-mcp.mcpb da versão mais recente e arraste-o para Configurações → Extensões. Você será solicitado a informar a URL do seu Coolify e o token — 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 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 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 o ~/.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 de Configurações > API do Coolify
`COOLIFY_ALLOW_WRITE`	`true`	Habilita operações de escrita (criar, atualizar, excluir, implantar)
`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 obrigatório em solicitações `/mcp` (transporte HTTP). Defini-lo também altera o padrão de bind 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 exibe um aviso alto

Implantação do Zero

Com este MCP, você pode implantar um aplicativo 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`	Lista todos os projetos
`createProject`	Cria um novo projeto	✓
`updateProject`	Atualiza nome/descrição do projeto	✓
`deleteProject`	Exclui um projeto e todos os seus recursos	✓
`listEnvironments`	Lista ambientes em um projeto
`createEnvironment`	Cria um novo ambiente	✓

Servidores e Infraestrutura

Ferramenta	Descrição	Escrita
`listServers`	Lista todos os servidores
`getServer`	Obtém detalhes do servidor
`createServer`	Cria um novo servidor	✓
`validateServer`	Valida conexão do servidor
`listPrivateKeys`	Lista chaves privadas SSH
`createPrivateKey`	Cria uma nova chave SSH	✓
`listGithubApps`	Lista GitHub Apps configurados

Aplicativos - Leitura

Ferramenta	Descrição
`listApplications`	Lista todos os aplicativos (resumidos por padrão)
`getApplication`	Obtém detalhes do aplicativo (segredos mascarados por padrão)
`getLogs`	Obtém logs de execução do aplicativo

Aplicativos - Criação

Ferramenta	Descrição	Escrita
`createApplication`	Cria um aplicativo; `type` seleciona a origem: `public`, `private-github-app`, `private-deploy-key`, `dockerfile` ou `dockerimage`. Campos de longo alcance vão em `extra` e são validados por tipo.	✓

Implantações Docker Compose são criadas com createService passando docker_compose_raw — desde o Coolify v4.1 elas são serviços, não aplicativos.

Aplicativos - Gerenciamento

Ferramenta	Descrição	Escrita
`updateApplication`	Atualiza configuração do aplicativo	✓
`deleteApplication`	Exclui um aplicativo	✓
`startApplication`	Inicia um aplicativo	✓
`stopApplication`	Para um aplicativo	✓
`restartApplication`	Reinicia um aplicativo	✓

Variáveis de Ambiente

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

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

Implantações

Ferramenta	Descrição	Escrita
`deploy`	Dispara uma implantação; `wait: true` consulta até o status final e retorna uma cauda de log em caso de falha	✓
`diagnoseApp`	Diagnostica um aplicativo por UUID, nome ou domínio: status, implantações recentes, cauda de log de falha, logs de execução, dicas
`diagnoseServer`	Diagnostica um servidor por UUID, nome ou IP: detalhamento de status de recursos, domínios, dicas
`listDeployments`	Lista implantações em execução
`getDeployment`	Obtém status e logs da implantação
`listAppDeployments`	Lista implantações de um aplicativo
`cancelDeployment`	Cancela uma implantação em execução	✓

Bancos de Dados

Ferramenta	Descrição	Escrita
`listDatabases`	Lista todos os bancos de dados
`getDatabase`	Obtém detalhes do banco de dados
`createDatabase`	Cria um banco de dados; `type` seleciona o mecanismo: postgresql, mysql, mariadb, mongodb, redis, keydb, dragonfly, clickhouse	✓
`updateDatabase`	Atualiza configuração do banco de dados	✓
`deleteDatabase`	Exclui um banco de dados (volumes/configurações excluídos por padrão)	✓
`controlDatabase`	Inicia, para ou reinicia um banco de dados	✓
`databaseBackups`	Gerencia agendamentos e execuções de backup (listar/criar/atualizar/excluir/listar_execuções/excluir_execução)	✓
`databaseEnvs`	Gerencia variáveis de ambiente do banco de dados (listar/criar/atualizar/bulk_update/excluir)	✓

Serviços

Ferramenta	Descrição	Escrita
`listServices`	Lista serviços
`getService`	Obtém detalhes do serviço (segredos mascarados por padrão)
`createService`	Cria um serviço de um clique ou implantação Docker Compose	✓
`updateService`	Atualiza um serviço	✓
`deleteService`	Exclui um serviço	✓
`controlService`	Inicia, para ou reinicia um serviço	✓
`serviceEnvs`	Gerencia variáveis de ambiente do serviço (listar/criar/atualizar/bulk_update/excluir)	✓

Armazenamentos, Tarefas Agendadas e Previews

Ferramenta	Descrição	Escrita
`storages`	Gerencia volumes persistentes e montagens de arquivo para aplicativos, bancos de dados e serviços	✓
`scheduledTasks`	Gerencia tarefas cron para aplicativos e serviços, incluindo histórico de execuções	✓
`deletePreview`	Exclui uma implantação de preview pelo ID da pull request	✓

Equipes, Servidores e Git

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

Operações em Lote

Ferramenta	Descrição	Escrita
`getInfrastructureOverview`	Resumo em uma chamada de servidores, projetos, aplicativos (detalhamento de status), bancos de dados, serviços e implantações em execução
`restartProjectApps`	Reinicia todos os aplicativos em um projeto ou ambiente (solicita confirmação)	✓
`redeployProject`	Dispara uma implantação para todos os aplicativos em um projeto ou ambiente (solicita confirmação)	✓
`stopAllApplications`	Parada de emergência de todos os aplicativos em execução, opcionalmente por projeto (solicita confirmação, indicando o raio de impacto)	✓

Outros

Ferramenta	Descrição
`listResources`	Lista todos os recursos com filtragem
`searchDocs`	Pesquisa de texto completo na documentação oficial do Coolify (índice incluído, sem rede)
`getHealth`	Verifica se a API do Coolify está no ar

Recursos de Segurança

Proteção Contra Escrita

Desative todas as operações de escrita:

COOLIFY_ALLOW_WRITE=false

Ocultação de Segredos

Os valores das variáveis de ambiente são mascarados por padrão
As credenciais do banco de dados são ocultadas
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 solicitação para /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 exibe um aviso alto: qualquer pessoa que consiga 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, aplicativo, banco de dados, serviço, servidor ou chave privada solicita sua confirmação primeiro, informando o que será perdido. Clientes sem elicitação se comportam exatamente como antes. Uma recusa, cancelamento ou tempo limite aborta a chamada; defina COOLIFY_MCP_ELICITATION=off para desativar totalmente os avisos.

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 está definida em src/coolify/constants.ts. Para atualizar:

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

Listagens no 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 Claude Code

CLI OpenAI Codex

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

Variáveis de Ambiente

Implantação do Zero

Referência de Ferramentas

Projetos e Ambientes

Servidores e Infraestrutura

Aplicativos - Leitura

Aplicativos - Criação

Aplicativos - Gerenciamento

Variáveis de Ambiente

Implantações

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

Ocultação de Segredos

Reforço do Transporte HTTP

Confirmação Humana em Exclusões Destrutivas

Desenvolvimento

Scripts

Versão Fixada do Coolify

Listagens no Registro

Exemplos de Clientes MCP

Cliente HTTP

Cliente Stdio

Licença

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