Coolify MCP Server

Um servidor MCP para integração com Coolify, a alternativa auto-hospedável ao Netlify e Vercel.

Documentação

Servidor MCP Coolify

Um servidor MCP (Model Context Protocol) robusto em TypeScript para integração com o Coolify, a alternativa auto-hospedável ao Netlify e Vercel.

Recursos

Integração completa com a API do Coolify: Gerencie aplicações, bancos de dados, servidores, projetos e serviços
Type-Safe: Suporte completo a TypeScript com definições de tipos abrangentes
Protocolo MCP: Compatível com Claude e outros clientes MCP
Acesso a Recursos: Exponha recursos do Coolify por meio de endpoints de recursos MCP
Suporte a Ferramentas: Conjunto abrangente de ferramentas para operações do Coolify

Instalação

npm install
npm run build

Configuração

Variáveis de Ambiente

O servidor requer variáveis de ambiente para conectar-se à sua instância do Coolify:

export COOLIFY_API_URL="http://localhost:8000"
export COOLIFY_API_TOKEN="your-api-token-here"
export COOLIFY_TEAM_ID="optional-team-id"  # Optional

Ou crie um arquivo .env:

COOLIFY_API_URL=http://localhost:8000
COOLIFY_API_TOKEN=your-api-token-here
COOLIFY_TEAM_ID=optional-team-id

Configuração do Cliente MCP

Claude Desktop

Adicione o servidor ao seu arquivo de configuração do Claude Desktop:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "coolify": {
      "command": "node",
      "args": ["/path/to/coolify-mcp-server/dist/index.js"],
      "env": {
        "COOLIFY_API_URL": "http://localhost:8000",
        "COOLIFY_API_TOKEN": "your-api-token-here",
        "COOLIFY_TEAM_ID": "optional-team-id"
      }
    }
  }
}

Alternativa: Uso via NPX

Se você publicar no npm, os usuários poderão executar via npx:

{
  "mcpServers": {
    "coolify": {
      "command": "npx",
      "args": ["@joshuarileydev/coolify-mcp-server", "--yes"],
      "env": {
        "COOLIFY_API_URL": "http://localhost:8000",
        "COOLIFY_API_TOKEN": "your-api-token-here",
        "COOLIFY_TEAM_ID": "optional-team-id"
      }
    }
  }
}

Ou use o nome do executável diretamente:

{
  "mcpServers": {
    "coolify": {
      "command": "npx",
      "args": ["coolify-mcp-server", "--yes"],
      "env": {
        "COOLIFY_API_URL": "http://localhost:8000",
        "COOLIFY_API_TOKEN": "your-api-token-here",
        "COOLIFY_TEAM_ID": "optional-team-id"
      }
    }
  }
}

Configuração de Desenvolvimento

Para desenvolvimento, você pode usar o código-fonte TypeScript diretamente:

{
  "mcpServers": {
    "coolify": {
      "command": "npx",
      "args": ["tsx", "/path/to/coolify-mcp-server/src/index.ts"],
      "env": {
        "COOLIFY_API_URL": "http://localhost:8000",
        "COOLIFY_API_TOKEN": "your-api-token-here",
        "COOLIFY_TEAM_ID": "optional-team-id"
      }
    }
  }
}

Outros Clientes MCP

Para outros clientes MCP que suportam variáveis de ambiente, certifique-se de que as seguintes variáveis estejam definidas:

COOLIFY_API_URL (obrigatório)
COOLIFY_API_TOKEN (obrigatório)
COOLIFY_TEAM_ID (opcional)

Exemplo de script shell:

#!/bin/bash
export COOLIFY_API_URL="http://localhost:8000"
export COOLIFY_API_TOKEN="your-api-token-here"
export COOLIFY_TEAM_ID="your-team-id"

node /path/to/coolify-mcp-server/dist/index.js

Ferramentas Disponíveis

Aplicações

list_applications - Listar todas as aplicações
get_application - Obter detalhes da aplicação
create_application - Criar nova aplicação
start_application - Iniciar uma aplicação
stop_application - Parar uma aplicação
restart_application - Reiniciar uma aplicação
deploy_application - Implantar uma aplicação

Bancos de Dados

list_databases - Listar todos os bancos de dados
create_database - Criar novo banco de dados

Servidores

list_servers - Listar todos os servidores
create_server - Criar novo servidor
validate_server - Validar conexão do servidor

Projetos

list_projects - Listar todos os projetos
create_project - Criar novo projeto

Serviços

list_services - Listar todos os serviços
start_service - Iniciar um serviço
stop_service - Parar um serviço

Sistema

get_version - Obter versão do Coolify

Recursos Disponíveis

O servidor expõe os seguintes recursos MCP:

coolify://applications - Todas as aplicações
coolify://databases - Todos os bancos de dados
coolify://servers - Todos os servidores
coolify://projects - Todos os projetos
coolify://services - Todos os serviços
coolify://teams - Todas as equipes

Configuração do Token da API

Faça login na sua instância do Coolify
Navegue até "Keys & Tokens" > "API tokens"
Clique em "Create New Token"
Escolha as permissões apropriadas:
- read-only: Somente leitura de dados
- read:sensitive: Leitura com dados sensíveis
- *: Acesso total (recomendado para o servidor MCP)
Copie o token gerado

Nota de Segurança

Ao usar o servidor MCP com o Claude Desktop ou outros clientes, seu token da API será armazenado no arquivo de configuração. Certifique-se de que este arquivo tenha as permissões apropriadas:

# macOS/Linux
chmod 600 ~/Library/Application\ Support/Claude/claude_desktop_config.json

# Or set environment variables in your shell profile instead
echo 'export COOLIFY_API_TOKEN="your-token-here"' >> ~/.bashrc

Desenvolvimento

# Install dependencies
npm install

# Run in development mode (requires env vars)
COOLIFY_API_URL=http://localhost:8000 COOLIFY_API_TOKEN=your-token npm run dev

# Build for production
npm run build

# Run built version
npm start

# Lint code
npm run lint

# Type check
npm run typecheck

Solução de Problemas

Problemas Comuns

"COOLIFY_API_URL and COOLIFY_API_TOKEN environment variables are required"
- Certifique-se de que as variáveis de ambiente estejam definidas antes de iniciar o servidor
- Verifique se o seu arquivo .env está no local correto
- Confirme se os nomes das variáveis estão escritos corretamente
"Tool execution failed: Request failed"
- Verifique se sua instância do Coolify está em execução e acessível
- Confirme se a URL da API está correta (inclua o protocolo: http:// ou https://)
- Certifique-se de que seu token da API tenha as permissões necessárias
Servidor MCP não aparecendo no Claude Desktop
- Reinicie o Claude Desktop após atualizar a configuração
- Verifique se o caminho do arquivo de configuração está correto para o seu sistema operacional
- Valide a sintaxe JSON no arquivo de configuração

Modo de Depuração

Para ver mensagens de erro detalhadas, execute o servidor com saída de depuração:

DEBUG=* node dist/index.js

Licença

MIT