edgarfelipe/mcp-coolify-server

MCP Coolify Server

Um servidor MCP (Model Context Protocol) para integração com Coolify, permitindo gerenciamento de aplicações, deployments e infraestrutura através de comandos de IA.

🚀 Funcionalidades

• Gerenciamento de Aplicações: Listar, criar, parar, reiniciar aplicações
• Deploy Automatizado: Fazer deploy de aplicações com força de rebuild
• Monitoramento: Visualizar logs e status de deployments
• Gestão de Serviços: Listar e gerenciar serviços do Coolify
• SSH Híbrido: Suporte a conexões SSH para operações avançadas
• Cache Redis: Sistema de cache para melhor performance

📋 Pré-requisitos

• Node.js 18+
• Docker e Docker Compose
• Instância do Coolify configurada
• Token de API do Coolify

🛠️ Instalação

1. Clone o repositório

git clone https://github.com/edgarfelipe/mcp-coolify-server.git
cd mcp-coolify-server

2. Configure as variáveis de ambiente

cp .env.example .env

Edite o arquivo .env com suas configurações:

COOLIFY_URL=https://sua-instancia-coolify.com
COOLIFY_API_TOKEN=seu-token-api-aqui
COOLIFY_TOKEN=seu-token-coolify-aqui
REDIS_URL=redis://localhost:6379

3. Execute com Docker Compose

docker compose up -d

4. Ou execute localmente

npm install
npm run build
npm start

🔧 Configuração

Variáveis de Ambiente

Obtendo Token de API do Coolify

1. Acesse sua instância do Coolify
2. Vá em Settings → API Tokens
3. Crie um novo token com as permissões necessárias
4. Copie o token gerado

📚 Uso

Comandos Disponíveis

Aplicações

• coolify_list_applications - Lista todas as aplicações
• coolify_get_application - Obtém detalhes de uma aplicação
• coolify_deploy_application - Faz deploy de uma aplicação
• coolify_stop_application - Para uma aplicação
• coolify_restart_application - Reinicia uma aplicação

Deployments

• coolify_get_deployments - Lista deployments de uma aplicação
• coolify_get_logs - Obtém logs de uma aplicação

Serviços

• coolify_list_services - Lista todos os serviços
• coolify_server_status - Verifica status do servidor

Exemplo de Uso com MCP Client

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

const client = new Client({
  name: 'coolify-client',
  version: '1.0.0'
});

// Listar aplicações
const apps = await client.request({
  method: 'tools/call',
  params: {
    name: 'coolify_list_applications',
    arguments: {}
  }
});

// Fazer deploy
const deploy = await client.request({
  method: 'tools/call',
  params: {
    name: 'coolify_deploy_application',
    arguments: {
      id: 123,
      force: true
    }
  }
});

🏗️ Arquitetura

┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   MCP Client    │────│  MCP Server     │────│   Coolify API   │
│   (AI Agent)    │    │  (Este Repo)    │    │   (Instância)   │
└─────────────────┘    └─────────────────┘    └─────────────────┘
                              │
                       ┌─────────────────┐
                       │   Redis Cache   │
                       │   (Opcional)    │
                       └─────────────────┘

🔒 Segurança

• Todas as comunicações com a API do Coolify são feitas via HTTPS
• Tokens são validados antes de cada operação
• Logs não expõem informações sensíveis
• Suporte a autenticação SSH para operações avançadas

🐛 Troubleshooting

Erro: "COOLIFY_URL is required"

• Verifique se a variável COOLIFY_URL está definida no .env
• Certifique-se de que a URL está no formato correto (https://...)

Erro: "COOLIFY_API_TOKEN is required"

• Verifique se o token de API está configurado corretamente
• Teste o token diretamente na API do Coolify

Container reiniciando constantemente

• Verifique os logs: docker logs coolify-mcp-hybrid
• Confirme se todas as variáveis de ambiente estão definidas

🤝 Contribuição

1. Fork o projeto
2. Crie uma branch para sua feature (git checkout -b feature/AmazingFeature)
3. Commit suas mudanças (git commit -m 'Add some AmazingFeature')
4. Push para a branch (git push origin feature/AmazingFeature)
5. Abra um Pull Request

📄 Licença

Este projeto está sob a licença MIT. Veja o arquivo para mais detalhes.

👨‍💻 Autor

Edgar Felipe - @edgarfelipe

⭐ Se este projeto te ajudou, considere dar uma estrela no repositório!