Coolify MCP Server

# Coolify MCP Server <img src="graphics/CoolifyMCP.png" width="256" alt="Coolify MCP Logo" /> A comprehensive Model Context Protocol (MCP) server for the Coolify API. This server enables AI assistants to manage infrastructure, applications, databases, services, and more through your self-hosted Coolify PaaS platform. > **Compatibility:** Tested with Coolify version 4.0.0-beta.418 --- **👋 Open for Opportunities!** I'm actively seeking new opportunities and collaborations. If you have interesting projects or job opportunities, feel free to reach out! 📧 **Contact:** pashvc@gmail.com --- ## Prerequisites - Node.js 18 or higher - Coolify Base URL - Coolify API token ## Features ### Core Management - **Teams**: List teams, get team details, view team members - **Projects**: Create, list, update, and delete projects - **Servers**: Create servers, validate connections, view resources and domains - **Private Keys**: Manage SSH keys for server access ### Applications - Full CRUD operations (create, read, update, delete) - Lifecycle management (start, stop, restart) - Execute commands in containers - View application logs - Git integration (repository, branch, commit management) - Resource limits configuration (memory, CPU) - Health check configuration ### Databases - Support for PostgreSQL, MySQL, MariaDB, MongoDB, and Redis - Create and manage database instances - Configure database-specific settings - Lifecycle management (start, stop, restart) - Resource limits and public port configuration ### Services - Deploy pre-configured services (Plausible, Umami, n8n, etc.) - Service lifecycle management - Configuration updates ### Environment Variables - Manage environment variables for applications, services, and databases - Support for build-time and runtime variables - Preview deployment variables - Shared variables across environments ### Deployments - List all deployments - Get deployment details and logs - Trigger deployments via webhook - Support for Docker image tags ### Developer Experience - Pre-configured prompts for common workflows - Comprehensive error handling with detailed messages - TypeScript support with full type safety - Integration with MCP Inspector for debugging - Robust API response handling for different Coolify versions - Extensive test coverage with both unit and integration tests ## Installation ```bash # Install globally npm install -g @pashvc/mcp-server-coolify # Or use with npx npx @pashvc/mcp-server-coolify ``` ## Configuration The server requires two environment variables: - `COOLIFY_BASE_URL`: The base URL of your Coolify instance - `COOLIFY_TOKEN`: Your Coolify API token ### Getting an API Token 1. Go to your Coolify instance 2. Navigate to `Keys & Tokens` / `API tokens` 3. Create a new token with the following required permissions: - read (for fetching information) - write (for managing resources) - deploy (for deployment operations) ## Usage ### In MCP Settings Add the following to your MCP settings configuration: ```json { "mcpServers": { "coolify": { "command": "npx", "args": ["-y", "@pashvc/mcp-server-coolify"], "env": { "COOLIFY_BASE_URL": "your-coolify-url", "COOLIFY_TOKEN": "your-api-token" }, "disabled": false, "autoApprove": [] } } } ``` Windows Cline users may need the following: ```json { "mcpServers": { "coolify": { "command": "cmd", "args": [ "/c", "npx", "-y", "@pashvc/mcp-server-coolify" ], "env": { "COOLIFY_BASE_URL": "your-coolify-url", "COOLIFY_TOKEN": "your-api-token" }, "disabled": false, "autoApprove": [] } } } ``` ### Available Tools #### Version & Health - `coolify_version`: Get Coolify version information - `coolify_health`: Check Coolify API health status #### Teams - `list_teams`: List all teams - `get_team`: Get details of a specific team - `get_current_team`: Get current team details - `get_current_team_members`: Get current team members #### Servers - `list_servers`: List all servers - `create_server`: Create a new server - `validate_server`: Validate server configuration - `get_server_resources`: Get server resources - `get_server_domains`: Get server domains #### Projects - `list_projects`: List all projects - `get_project`: Get project details - `create_project`: Create a new project - `update_project`: Update project settings - `delete_project`: Delete a project #### Applications - `list_applications`: List all applications - `get_application`: Get application details - `create_application`: Create a new application - `update_application`: Update application settings - `delete_application`: Delete an application - `start_application`: Start an application - `stop_application`: Stop an application - `restart_application`: Restart an application - `execute_command`: Execute command in application container - `get_application_logs`: Get application logs #### Databases - `list_databases`: List all databases - `get_database`: Get database details - `create_database`: Create a new database - `update_database`: Update database settings - `delete_database`: Delete a database - `start_database`: Start a database - `stop_database`: Stop a database - `restart_database`: Restart a database #### Services - `list_services`: List all services - `get_service`: Get service details - `create_service`: Create a new service - `update_service`: Update service settings - `delete_service`: Delete a service - `start_service`: Start a service - `stop_service`: Stop a service - `restart_service`: Restart a service #### Environment Variables - `list_environment_variables`: List environment variables - `create_environment_variable`: Create a new environment variable - `update_environment_variable`: Update an environment variable - `delete_environment_variable`: Delete an environment variable #### Deployments - `list_deployments`: List all deployments - `get_deployment`: Get deployment details - `deploy_webhook`: Trigger deployment via webhook #### Private Keys - `list_private_keys`: List all private keys - `create_private_key`: Create a new private key - `update_private_key`: Update a private key - `delete_private_key`: Delete a private key ### Pre-configured Prompts The server includes helpful prompts for common workflows: - `deploy-git-app`: Deploy a new application from a Git repository - `setup-database`: Set up a new database with proper configuration - `deploy-service`: Deploy a pre-configured service - `environment-setup`: Set up environment variables for an application - `server-health-check`: Comprehensive health check of all servers - `backup-database`: Create a backup of a database - `scale-application`: Scale an application by adjusting resources - `setup-ssl`: Configure SSL/TLS for an application - `migrate-application`: Migrate an application between servers - `troubleshoot-deployment`: Troubleshoot a failed deployment ## Development ### Building from Source ```bash # Clone the repository git clone https://github.com/pashvc/mcp-server-coolify.git cd mcp-server-coolify # Install dependencies npm install # Build the project npm run build # Run tests npm test ``` ### Development Scripts - `npm run build`: Build the TypeScript project - `npm run watch`: Build and watch for changes - `npm test`: Run all tests - `npm run test:watch`: Run tests in watch mode - `npm run test:coverage`: Run tests with coverage report - `npm run test:integration`: Run integration tests only (requires env vars) - `npm run inspector`: Launch MCP Inspector for debugging ## Troubleshooting ### Common Issues - **404 Errors**: Some endpoints may not be available in all Coolify versions. The server automatically handles different response formats across versions. - **Authentication Errors**: Ensure your API token has the required permissions (read, write, deploy). - **Connection Issues**: Verify your `COOLIFY_BASE_URL` is correct and accessible. - **Environment Variables**: Make sure both `COOLIFY_BASE_URL` and `COOLIFY_TOKEN` are set correctly. ### Testing Your Setup ```bash # Test with your credentials export COOLIFY_BASE_URL="https://your-coolify-instance.com" export COOLIFY_TOKEN="your-api-token" # Run integration tests to verify connectivity npm run test:integration # Or test the server directly npm run build && npm start ``` ### API Compatibility The server handles different response formats automatically: - **Version endpoint**: Supports both string and object responses - **List endpoints**: Handles both direct arrays and paginated responses - **Health endpoint**: Adapts to different status response formats - **Error handling**: Robust parsing of various error message formats ## License MIT