Coolify MCP Server
The most comprehensive MCP server for Coolify - 35 optimized tools, smart diagnostics, and batch operations for managing your self-hosted PaaS through AI assistants.
A Model Context Protocol (MCP) server for Coolify, enabling AI assistants to manage and debug your Coolify instances through natural language.
Features
This MCP server provides 35 token-optimized tools for debugging, management, and deployment:
| Category | Tools |
|---|---|
| Infrastructure | get_infrastructure_overview, get_mcp_version, get_version |
| Diagnostics | diagnose_app, diagnose_server, find_issues |
| Batch Operations | restart_project_apps, bulk_env_update, stop_all_apps, redeploy_project |
| Servers | list_servers, get_server, validate_server, server_resources, server_domains |
| Projects | projects (list, get, create, update, delete via action param) |
| Environments | environments (list, get, create, delete via action param) |
| Applications | list_applications, get_application, application (CRUD), application_logs |
| Databases | list_databases, get_database, database (create 8 types, delete), database_backups (CRUD schedules, view executions) |
| Services | list_services, get_service, service (create, update, delete) |
| Control | control (start/stop/restart for apps, databases, services) |
| Env Vars | env_vars (CRUD for application and service env vars) |
| Deployments | list_deployments, deploy, deployment (get, cancel, list_for_app) |
| Private Keys | private_keys (list, get, create, update, delete via action param) |
| GitHub Apps | github_apps (list, get, create, update, delete via action param) |
Token-Optimized Design
The server uses 85% fewer tokens than a naive implementation (6,600 vs 43,000) by consolidating related operations into single tools with action parameters. This prevents context window exhaustion in AI assistants.
Installation
Prerequisites
- Node.js >= 18
- A running Coolify instance (tested with v4.0.0-beta.460)
- Coolify API access token (generate in Coolify Settings > API)
Claude Desktop
Add to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):
{
"mcpServers": {
"coolify": {
"command": "npx",
"args": ["-y", "@masonator/coolify-mcp"],
"env": {
"COOLIFY_ACCESS_TOKEN": "your-api-token",
"COOLIFY_BASE_URL": "https://your-coolify-instance.com"
}
}
}
}
Claude Code
claude mcp add coolify \
-e COOLIFY_BASE_URL="https://your-coolify-instance.com" \
-e COOLIFY_ACCESS_TOKEN="your-api-token" \
-- npx @masonator/coolify-mcp@latest
Note: Use
@latesttag (not-yflag) for reliable startup in Claude Code CLI.
Cursor
env COOLIFY_ACCESS_TOKEN=your-api-token COOLIFY_BASE_URL=https://your-coolify-instance.com npx -y @masonator/coolify-mcp
Context-Optimized Responses
Why This Matters
The Coolify API returns extremely verbose responses - a single application can contain 91 fields including embedded 3KB server objects and 47KB docker-compose files. When listing 20+ applications, responses can exceed 200KB, which quickly exhausts the context window of AI assistants like Claude Desktop.
This MCP server solves this by returning optimized summaries by default.
How It Works
| Tool Type | Returns | Use Case |
|---|---|---|
list_* | Summaries only (uuid, name, status, etc) | Discovery, finding resources |
get_* | Full details for a single resource | Deep inspection, debugging |
get_infrastructure_overview | All resources summarized in one call | Start here to understand your setup |
Response Size Comparison
| Endpoint | Full Response | Summary Response | Reduction |
|---|---|---|---|
| list_applications | ~170KB | ~4.4KB | 97% |
| list_services | ~367KB | ~1.2KB | 99% |
| list_servers | ~4KB | ~0.4KB | 90% |
| list_application_envs | ~3KB/var | ~0.1KB/var | 97% |
| deployment get | ~13KB | ~1KB | 92% |
HATEOAS-style Response Actions
Responses include contextual _actions suggesting relevant next steps:
{
"data": { "uuid": "abc123", "status": "running" },
"_actions": [
{ "tool": "application_logs", "args": { "uuid": "abc123" }, "hint": "View logs" },
{
"tool": "control",
"args": { "resource": "application", "action": "restart", "uuid": "abc123" },
"hint": "Restart"
}
],
"_pagination": { "next": { "tool": "list_applications", "args": { "page": 2 } } }
}
This helps AI assistants understand logical next steps without consuming extra tokens.
Recommended Workflow
- Start with overview:
get_infrastructure_overview- see everything at once - Find your target:
list_applications- get UUIDs of what you need - Dive deep:
get_application(uuid)- full details for one resource - Take action:
control(resource: 'application', action: 'restart'),application_logs(uuid), etc.
Pagination
All list endpoints still support optional pagination for very large deployments:
# Get page 2 with 10 items per page
list_applications(page=2, per_page=10)
Example Prompts
Getting Started
Give me an overview of my infrastructure
Show me all my applications
What's running on my servers?
Debugging & Monitoring
Diagnose my stuartmason.co.uk app
What's wrong with my-api application?
Check the status of server 192.168.1.100
Find any issues in my infrastructure
Get the logs for application {uuid}
What environment variables are set for application {uuid}?
Show me recent deployments for application {uuid}
What resources are running on server {uuid}?
Application Management
Restart application {uuid}
Stop the database {uuid}
Start service {uuid}
Deploy application {uuid} with force rebuild
Update the DATABASE_URL env var for application {uuid}
Project Setup
Create a new project called "my-app"
Create a staging environment in project {uuid}
Deploy my app from private GitHub repo org/repo on branch main
Deploy nginx:latest from Docker Hub
Deploy from public repo https://github.com/org/repo
Environment Variables
| Variable | Required | Default | Description |
|---|---|---|---|
COOLIFY_ACCESS_TOKEN | Yes | - | Your Coolify API token |
COOLIFY_BASE_URL | No | http://localhost:3000 | Your Coolify instance URL |
Development
# Clone and install
git clone https://github.com/stumason/coolify-mcp.git
cd coolify-mcp
npm install
# Build
npm run build
# Test
npm test
# Run locally
COOLIFY_BASE_URL="https://your-coolify.com" \
COOLIFY_ACCESS_TOKEN="your-token" \
node dist/index.js
Available Tools
Infrastructure
get_version- Get Coolify API versionget_mcp_version- Get coolify-mcp server version (useful to verify which version is installed)get_infrastructure_overview- Get a high-level overview of all infrastructure (servers, projects, applications, databases, services)
Diagnostics (Smart Lookup)
These tools accept human-friendly identifiers instead of just UUIDs:
diagnose_app- Get comprehensive app diagnostics (status, logs, env vars, deployments). Accepts UUID, name, or domain (e.g., "stuartmason.co.uk" or "my-app")diagnose_server- Get server diagnostics (status, resources, domains, validation). Accepts UUID, name, or IP address (e.g., "coolify-apps" or "192.168.1.100")find_issues- Scan entire infrastructure for unhealthy apps, databases, services, and unreachable servers
Servers
list_servers- List all servers (returns summary)get_server- Get server detailsget_server_resources- Get resources running on a serverget_server_domains- Get domains configured on a servervalidate_server- Validate server connection
Projects
projects- Manage projects withaction: list|get|create|update|delete
Environments
environments- Manage environments withaction: list|get|create|delete
Applications
list_applications- List all applications (returns summary)get_application- Get application detailsapplication_logs- Get application logsapplication- Create, update, or delete apps withaction: create_public|create_github|create_key|create_dockerimage|update|delete- Deploy from public repos, private GitHub, SSH keys, or Docker images
- Configure health checks (path, interval, retries, etc.)
env_vars- Manage env vars withresource: application, action: list|create|update|deletecontrol- Start/stop/restart withresource: application, action: start|stop|restart
Databases
list_databases- List all databases (returns summary)get_database- Get database detailsdatabase- Create or delete databases withaction: create|delete, type: postgresql|mysql|mariadb|mongodb|redis|keydb|clickhouse|dragonflydatabase_backups- Manage backup schedules withaction: list_schedules|get_schedule|create|update|delete|list_executions|get_execution- Configure frequency, retention policies, S3 storage
- Enable/disable schedules without deletion
- View backup execution history
control- Start/stop/restart withresource: database, action: start|stop|restart
Services
list_services- List all services (returns summary)get_service- Get service detailsservice- Create, update, or delete services withaction: create|update|deleteenv_vars- Manage env vars withresource: service, action: list|create|deletecontrol- Start/stop/restart withresource: service, action: start|stop|restart
Deployments
list_deployments- List running deployments (returns summary)deploy- Deploy by tag or UUIDdeployment- Manage deployments withaction: get|cancel|list_for_app(supportslinesparam to limit log output)
Private Keys
private_keys- Manage SSH keys withaction: list|get|create|update|delete
Batch Operations
Power user tools for operating on multiple resources at once:
restart_project_apps- Restart all applications in a projectbulk_env_update- Update or create an environment variable across multiple applications (upsert behavior)stop_all_apps- Emergency stop all running applications (requires confirmation)redeploy_project- Redeploy all applications in a project with force rebuild
Why Coolify MCP?
- Context-Optimized: Responses are 90-99% smaller than raw API, preventing context window exhaustion
- Smart Lookup: Find apps by domain (
stuartmason.co.uk), servers by IP, not just UUIDs - Batch Operations: Restart entire projects, bulk update env vars, emergency stop all apps
- Production Ready: 98%+ test coverage, TypeScript strict mode, comprehensive error handling
- Always Current: Weekly OpenAPI drift detection ensures the server stays in sync with Coolify
Related Links
- Coolify - The open-source & self-hostable Heroku/Netlify/Vercel alternative
- Model Context Protocol - The protocol powering AI tool integrations
- MCP Server Registry - Official MCP server directory
Contributing
Contributions welcome! Please see CONTRIBUTING.md for guidelines.
License
MIT - see LICENSE for details.
Support
If you find this useful, please ⭐ star the repo!