Coolify MCP Server
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
# 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 instanceCOOLIFY_TOKEN: Your Coolify API token
Getting an API Token
- Go to your Coolify instance
- Navigate to
Keys & Tokens/API tokens - 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:
{
"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:
{
"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 informationcoolify_health: Check Coolify API health status
Teams
list_teams: List all teamsget_team: Get details of a specific teamget_current_team: Get current team detailsget_current_team_members: Get current team members
Servers
list_servers: List all serverscreate_server: Create a new servervalidate_server: Validate server configurationget_server_resources: Get server resourcesget_server_domains: Get server domains
Projects
list_projects: List all projectsget_project: Get project detailscreate_project: Create a new projectupdate_project: Update project settingsdelete_project: Delete a project
Applications
list_applications: List all applicationsget_application: Get application detailscreate_application: Create a new applicationupdate_application: Update application settingsdelete_application: Delete an applicationstart_application: Start an applicationstop_application: Stop an applicationrestart_application: Restart an applicationexecute_command: Execute command in application containerget_application_logs: Get application logs
Databases
list_databases: List all databasesget_database: Get database detailscreate_database: Create a new databaseupdate_database: Update database settingsdelete_database: Delete a databasestart_database: Start a databasestop_database: Stop a databaserestart_database: Restart a database
Services
list_services: List all servicesget_service: Get service detailscreate_service: Create a new serviceupdate_service: Update service settingsdelete_service: Delete a servicestart_service: Start a servicestop_service: Stop a servicerestart_service: Restart a service
Environment Variables
list_environment_variables: List environment variablescreate_environment_variable: Create a new environment variableupdate_environment_variable: Update an environment variabledelete_environment_variable: Delete an environment variable
Deployments
list_deployments: List all deploymentsget_deployment: Get deployment detailsdeploy_webhook: Trigger deployment via webhook
Private Keys
list_private_keys: List all private keyscreate_private_key: Create a new private keyupdate_private_key: Update a private keydelete_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 repositorysetup-database: Set up a new database with proper configurationdeploy-service: Deploy a pre-configured serviceenvironment-setup: Set up environment variables for an applicationserver-health-check: Comprehensive health check of all serversbackup-database: Create a backup of a databasescale-application: Scale an application by adjusting resourcessetup-ssl: Configure SSL/TLS for an applicationmigrate-application: Migrate an application between serverstroubleshoot-deployment: Troubleshoot a failed deployment
Development
Building from Source
# 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 projectnpm run watch: Build and watch for changesnpm test: Run all testsnpm run test:watch: Run tests in watch modenpm run test:coverage: Run tests with coverage reportnpm 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_URLis correct and accessible. - Environment Variables: Make sure both
COOLIFY_BASE_URLandCOOLIFY_TOKENare set correctly.
Testing Your Setup
# 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