io.github.StuMason/coolify MCP Server
io.github.StuMason/coolify
45 optimized tools for managing Coolify infrastructure, diagnostics, and deployments through AI assistants.
What this kind of tool is for
- Automate a build, test, or deployment step you repeat by hand.
- Review or refactor code in an existing repository without leaving your agent.
- Bridge an internal service or CLI into the agent toolset.
How to compare servers like this
- Scope of control:
- Repos and CI are hard to undo; prefer tools that ask before anything irreversible.
- Environment fit:
- Match the runtime it expects (Node, Python, a container) to what you actually run.
- Maintenance signal:
- Check the last-commit date — dev tooling that lags upstream breaks first.
- Config surface:
- Prefer tools whose environment-variable or config keys are documented plainly.
This page carries your copy-paste config: pick your MCP client in the install section on this page and use the copy button.
What is the io.github.StuMason/coolify MCP server?
The Coolify MCP Server is a Model Context Protocol server that provides 42 token-optimized tools for managing, debugging, and deploying Coolify self-hosted PaaS instances through natural language. It enables AI assistants like Claude and Cursor to control servers, applications, databases, services, and deployments while reducing API response sizes by up to 99% through context-aware summaries.
This MCP server bridges AI assistants with Coolify infrastructure management. It consolidates related operations into single tools with action parameters, reducing token usage by 85% compared to naive implementations. Features include infrastructure overview, smart diagnostics, batch operations, full CRUD for applications/databases/services, deployment management, GitHub integration, and full-text documentation search—all optimized for AI context windows.
How to install io.github.StuMason/coolify
Copy-paste configuration for popular MCP clients.
COOLIFY_ACCESS_TOKENrequiredsecretYour Coolify API access token
COOLIFY_BASE_URLYour Coolify instance URL
{
"mcpServers": {
"coolify": {
"command": "npx",
"args": [
"-y",
"@masonator/coolify-mcp"
],
"env": {
"COOLIFY_ACCESS_TOKEN": "<YOUR_COOLIFY_ACCESS_TOKEN>",
"COOLIFY_BASE_URL": "<YOUR_COOLIFY_BASE_URL>"
}
}
}
}Tools & capabilities
Tools this server exposes to the agent.
get_infrastructure_overview— Get a high-level overview of all infrastructure (servers, projects, applications, databases, services)diagnose_app— Get comprehensive app diagnostics (status, logs, env vars, deployments). Accepts UUID, name, or domaindiagnose_server— Get server diagnostics (status, resources, domains, validation). Accepts UUID, name, or IP addressfind_issues— Scan entire infrastructure for unhealthy apps, databases, services, and unreachable serverslist_servers— List all servers with summariesget_server— Get full server detailsserver_resources— Get resources running on a serverserver_domains— Get domains configured on a servervalidate_server— Validate server connectionprojects— Manage projects with action: list|get|create|update|deleteenvironments— Manage environments with action: list|get|create|deletelist_applications— List all applications with summariesget_application— Get full application detailsapplication_logs— Get application logsapplication— Create, update, or delete apps with action: create_public|create_github|create_key|create_dockerimage|update|deletelist_databases— List all databases with summariesget_database— Get full database detailsdatabase— Create or delete databases with action: create|delete, type: postgresql|mysql|mariadb|mongodb|redis|keydb|clickhouse|dragonflydatabase_backups— Manage backup schedules with action: list_schedules|get_schedule|create|update|delete|list_executions|get_executionlist_services— List all services with summaries
Use cases
- Diagnose failing applications and services by name, domain, or UUID without manual API calls
- Monitor infrastructure health and automatically detect unhealthy apps, databases, and unreachable servers
- Deploy applications from public repos, private GitHub, SSH keys, or Docker images with health check configuration
- Manage environment variables, backups, and scheduled tasks across multiple applications and databases
- Restart, stop, or redeploy entire projects and perform batch operations through natural language commands
io.github.StuMason/coolify MCP server FAQ
It's an MCP server that gives AI assistants like Claude and Cursor access to 42 optimized tools for managing Coolify self-hosted PaaS infrastructure. It reduces API response sizes by up to 99% through context-aware summaries, making it suitable for AI context windows.
Yes, the Coolify MCP Server is open-source under the MIT license and available on npm as @masonator/coolify-mcp.
Add it to your Claude Desktop config at ~/Library/Application Support/Claude/claude_desktop_config.json with your COOLIFY_ACCESS_TOKEN and COOLIFY_BASE_URL environment variables, then run npx -y @masonator/coolify-mcp.
Run: env COOLIFY_ACCESS_TOKEN=your-token COOLIFY_BASE_URL=https://your-coolify.com npx -y @masonator/coolify-mcp
You need a Coolify API access token (generate in Coolify Settings > API) and the base URL of your Coolify instance. Optional custom headers can be passed for auth proxies like Cloudflare Zero Trust.
Yes, you can pass custom HTTP headers (e.g., Cloudflare Access credentials) via --header flags in the MCP configuration to support auth-proxy middleware.
README (reference)
Source of truth, from the repository.
Coolify MCP Server
The most comprehensive MCP server for Coolify - 42 optimized tools, smart diagnostics, documentation search, and batch operations for managing your self-hosted PaaS through AI assistants.
📖 Docs: coolify-mcp.stumason.dev — install guide, quickstart, full tools reference, MCP primer, Coolify API gotchas, contributing guide, and the public v3 roadmap.
💡 Building a Laravel app? Check out laravel-coolify — deploy Laravel to Coolify with a Horizon-style dashboard, Artisan commands, and auto-generated Dockerfiles.
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 42 token-optimized tools for debugging, management, and deployment:
| Category | Tools |
|---|---|
| Infrastructure | get_infrastructure_overview, get_mcp_version, get_version, system (health, list_resources, enable/disable API) |
| 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 + delete_preview), application_logs |
| Databases | list_databases, get_database, database (create 8 types, delete), database_backups (CRUD schedules, executions incl. delete) |
| Services | list_services, get_service, service (create, update, delete) |
| Control | control (start/stop/restart for apps, databases, services) |
| Env Vars | env_vars (CRUD + bulk_update for application, service, and database env vars) |
| Storages | storages (list, create, update, delete persistent/file storages for apps, databases, services) |
| Scheduled Tasks | scheduled_tasks (list, create, update, delete, list_executions for apps and services) |
| 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, list_repos, list_branches) |
| Teams | teams (list, get, get_members, get_current, get_current_members) |
| Cloud Tokens | cloud_tokens (Hetzner/DigitalOcean: list, get, create, update, delete, validate) |
| Hetzner Cloud | hetzner (list_locations, list_server_types, list_images, list_ssh_keys, create_server) |
| Documentation | search_docs (full-text search across Coolify docs) |
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
Custom HTTP Headers (Cloudflare Zero Trust, Auth Proxies)
If your Coolify instance sits behind a Cloudflare Access tunnel or other auth-proxy middleware, pass extra headers on every outbound request with --header:
{
"mcpServers": {
"coolify": {
"command": "npx",
"args": [
"-y",
"@masonator/coolify-mcp",
"--header",
"CF-Access-Client-Id: abc123.access",
"--header",
"CF-Access-Client-Secret: your-secret"
],
"env": {
"COOLIFY_ACCESS_TOKEN": "your-api-token",
"COOLIFY_BASE_URL": "https://your-coolify-instance.com"
}
}
}
}
Multiple --header flags can be combined. The reserved headers Authorization and Content-Type are filtered (with a warning) to prevent silently overriding the Coolify bearer token.
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% |
| deployment list_for_app | ~1MB | ~4KB | 99.6% |
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
Documentation & Help
How do I set up Docker Compose with Coolify?
Search the docs for health check configuration
How do I fix a 502 Bad Gateway error?
What are Coolify environment variables?
Teams & Cloud Providers
Who has access to my Coolify instance?
Show me the current team members
List my cloud provider tokens
Validate my Hetzner API token
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 detailsserver_resources- Get resources running on a serverserver_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(supportslinesandpageparams for paginated log output withlogs_meta)
Private Keys
private_keys- Manage SSH keys withaction: list|get|create|update|delete
GitHub Apps
github_apps- Manage GitHub App integrations withaction: list|get|create|update|delete
Teams
teams- Manage teams withaction: list|get|get_members|get_current|get_current_members
Cloud Tokens
cloud_tokens- Manage cloud provider tokens (Hetzner/DigitalOcean) withaction: list|get|create|update|delete|validate
Documentation
search_docs- Search Coolify documentation using full-text search. Indexes 1,500+ doc chunks on first call, returns ranked results with titles, URLs, and snippets (~849 tokens for 5 results)
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 - Docs Search: Built-in full-text search across Coolify documentation — your AI assistant can look up how-tos and troubleshooting without leaving the conversation
- Batch Operations: Restart entire projects, bulk update env vars, emergency stop all apps
- Production Ready: 98%+ test coverage, TypeScript strict mode, comprehensive error handling
Related Links
- stumason.dev - Author's site
- MCP Registry - Find this server as
io.github.StuMason/coolify - Coolify - The open-source & self-hostable Heroku/Netlify/Vercel alternative
- Model Context Protocol - The protocol powering AI tool integrations
Contributing
Contributions welcome! Please see CONTRIBUTING.md for guidelines.
License
MIT - see LICENSE for details.
Support
<p align="center"> Built by <a href="https://stumason.dev">Stu Mason</a> · If you find this useful, please ⭐ star the repo! </p>
Related MCP servers

Self-hosted Polar health analytics with built-in MCP server for sleep, HRV, workouts, and personal baselines.

Code-review MCP: review a GitLab MR or GitHub PR against the whole codebase, not just the diff.

DVERA drives CT verification of mission-critical C/C++: setup, analysis, tests, coverage.

io.github.SurgeX-Labs/awx-mcp-server
Control AWX/Ansible Tower through natural language with 49 automation tools
Oracle MCP Query Server (Node.js) - Read-only SELECT via MCP
View repository →
