Allows an AI client to deploy, diagnose, and manage applications, services, and databases on Coolify instances.
Also known as clezcoding/awesome-coolify, awesome-coolify-mcp
- Stars
- 0
- Tools
- 45
- Downloads, 30 days
- —
- Latest version
- 0.1.2
- Last commit
- Nov 14, 2026
- License
- MIT
What is Coolify MCP?
Coolify allows an AI client to deploy, diagnose, and manage applications, services, and databases on Coolify instances. It exposes 45 tools, such as health, version, verify.
Summary generated from the project's README
About Coolify MCP server
Managing self-hosted infrastructure through an AI coding agent is possible with awesome-coolify-mcp. This server allows developers to deploy, diagnose, and manage applications, services, and databases on Coolify instances directly from clients like Cursor, Claude, VS Code, or Windsurf. It acts as a bridge to the Coolify REST API 4.1.x, providing a consistent interface for interacting with your server fleet.
Instead of using many separate tools, the server provides 19 action-based tools that use a single command structure with an action field. Users can perform tasks such as watching deployments, inspecting logs, or running emergency operations. The setup requires providing a COOLIFY_URL and COOLIFY_TOKEN via environment variables in your MCP client configuration, or by registering multiple instances in a local JSON file.
Safety is built into the workflow through automatic secret masking for sensitive data like passwords and tokens. Destructive actions require an explicit confirmation flag to prevent accidental changes. The server also handles transient network issues with automatic retries and provides structured error codes to help the AI agent recover from failures gracefully.
What you can do with it
- 1Deploy and monitor applicationsAn AI agent can trigger a new deployment and watch the build progress in real time.
- 2Troubleshoot infrastructure issuesYou can ask the agent to scan your entire fleet to find out why something is failing.
- 3Manage database and service workloadsThe agent can create and manage various workloads including databases and services.
- 4Execute emergency operationsA developer can instruct the agent to perform high-stakes tasks like stopping all running processes.
Written from the project's README. Every use case is checked against a quote from it.
How to install Coolify MCP
Formats verified 10 Nov 2026Add to CursorAdd to GooseInstall Coolify MCP in Claude Code
$ claude mcp add awesome-coolify -- npx -y awesome-coolify-mcpInstall Coolify MCP in Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"awesome-coolify": {
"command": "npx",
"args": [
"-y",
"awesome-coolify-mcp"
]
}
}
}Install Coolify MCP in VS Code
.vscode/mcp.json
{
"servers": {
"awesome-coolify": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"awesome-coolify-mcp"
]
}
}
}Install Coolify MCP in VS Code CLI
$ code --add-mcp '{"name":"awesome-coolify","type":"stdio","command":"npx","args":["-y","awesome-coolify-mcp"]}'Install Coolify MCP in Claude Desktop
claude_desktop_config.json
{
"mcpServers": {
"awesome-coolify": {
"command": "npx",
"args": [
"-y",
"awesome-coolify-mcp"
]
}
}
}Install Coolify MCP in Codex
$ codex mcp add awesome-coolify -- npx -y awesome-coolify-mcpInstall Coolify MCP in Codex config.toml
~/.codex/config.toml
[mcp_servers.awesome-coolify] command = "npx" args = ["-y", "awesome-coolify-mcp"]
Install Coolify MCP in Gemini CLI
$ gemini mcp add -s user awesome-coolify npx -- -y awesome-coolify-mcpInstall Coolify MCP in Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"awesome-coolify": {
"command": "npx",
"args": [
"-y",
"awesome-coolify-mcp"
]
}
}
}Coolify MCP tools 45
Detected from the READMEhealthversionverifyinfrastructure_overviewlistfindappserverscanlogsanalyzeget
| health | — | |
| version | — | |
| verify | — | |
| infrastructure_overview | — | |
| list | — | |
| find | — | |
| app | — | |
| server | — | |
| scan | — | |
| logs | — | |
| analyze | — | |
| get | — |
Show all 45 toolsShow fewer tools
deploywatchcancelpreflightrollbackservicedatabasecreate-git-appcreate-app-dbcreate-one-clickrecommendapplicationvalidatecreatesearchstop_allredeploy_projectrestart_projectaddupdatedeleteset-defaultimport-envcloud-infoupsertsetremoveclearsyncdiffauditwireresume
| deploy | — | |
| watch | — | |
| cancel | — | |
| preflight | — | |
| rollback | — | |
| service | — | |
| database | — | |
| create-git-app | — | |
| create-app-db | — | |
| create-one-click | — | |
| recommend | — | |
| application | — | |
| validate | — | |
| create | — | |
| search | — | |
| stop_all | — | |
| redeploy_project | — | |
| restart_project | — | |
| add | — | |
| update | — | |
| delete | — | |
| set-default | — | |
| import-env | — | |
| cloud-info | — | |
| upsert | — | |
| set | — | |
| remove | — | |
| clear | — | |
| sync | — | |
| diff | — | |
| audit | — | |
| wire | — | |
| resume | — |
Configuration
COOLIFY_MCP_LOGCOOLIFY_TOKENCOOLIFY_URLCOOLIFY_VERIFY_SSL
| Name | Description | |
|---|---|---|
| COOLIFY_MCP_LOG | — | |
| COOLIFY_TOKEN | — | |
| COOLIFY_URL | — | |
| COOLIFY_VERIFY_SSL | — |
Automated checks
Ran Nov 13, 2026Full report →Passed our automated checks. That is not a security audit: read the code and give the server the narrowest access it needs. How checks work
- Source repository linked and reachablePass
- Open source license (OSI)Pass
- Commit or release in the last yearPass
- Package name not close to a popular packagePass
- Remote endpoint uses HTTPSNot checked
- Destructive tools are labelledNot checked
- No hidden instructions to the modelPass
- No critical advisory in the package or its dependenciesPass
README
View on GitHub📋 Table of contents
- Overview
- Why awesome-coolify-mcp
- Features
- How it works
- Quick start
- Install
- Coolify Cloud
- Supported clients
- Environment variables
- MCP Prompts
- Tools reference
- Safety model
- Structured errors & retries
- Example agent workflows
- Status today
- Coming soon
- Local development
- Links
🔭 Overview
Self-hosted Coolify is one of the best open-source alternatives to Heroku/Vercel-style PaaS platforms — but wiring it up to an AI coding agent has historically meant piecing together several small, overlapping community MCP integrations, each with its own schema, its own error format, and its own idea of what "safe" looks like.
awesome-coolify-mcp 1.1.4 replaces that patchwork with a single, community-maintained MCP server that speaks Coolify's REST API 4.1.x through a clean, action-based tool surface. Source, docs, and npm distribution live in one public repo — clezcoding/awesome-coolify — while the installable package stays awesome-coolify-mcp. Instead of memorizing dozens of near-identical tool names, your agent calls one of 19 tools with an action field:
application({ action: "deploy", uuid: "<app-uuid>", wait: false })
deployment({ action: "watch", deployment_uuid: "<deployment_uuid>", timeout: 300 })
diagnose({ action: "scan" })
emergency({ action: "stop_all", confirm: true })
Under the hood, every call goes through the same request pipeline: Zod-validated input, retrying HTTP client, secret-aware output masking, and structured error envelopes with recovery hints — so your agent fails gracefully instead of guessing.
[!NOTE] This is a community project built for people who run their own Coolify instances. It is not affiliated with or endorsed by Coolify Labs.
🆚 Why awesome-coolify-mcp
| Typical setup without it | With awesome-coolify-mcp |
|---|---|
| Several overlapping community MCP tools, each with its own schema | One server, one consistent schema |
| Dozens of granular, single-purpose tools per resource | 19 tools with consistent action discriminators |
| Ad-hoc error strings that agents have to guess at | Structured codes (COOLIFY_401, COOLIFY_404, …) + machine-readable recovery hints |
| Secrets can leak straight into agent context | Default secret masking + confirmation gates on destructive actions |
| Read a wall of raw JSON to find what changed | Bounded, paginated projections tuned for LLM context windows |
Today, the shipped surface covers day-2 operations and infrastructure creation: verify connectivity, discover fleets, deploy and watch builds, inspect bounded logs, diagnose incidents, run gated emergency ops, and manage applications, services, databases, SSH keys, servers, projects, environments, backups, and environment variables.
✨ Features
- 19 action-based tools — call
application({ action: "deploy", uuid })instead of hunting through dozens of granular tool names. The registered surface issystem,meta,resource,diagnose,application,emergency,deployment,service,database,private_key,instance,manifest,server,project,environment,docs,recipe,setup, andintelligence. - Multi-instance registry & routing — register every Coolify instance you own in
~/.coolify-mcp/instances.jsonvia theinstancetool; per-call credential resolution with no cross-instance leakage. - Coolify Cloud aware —
instance({ action: "cloud-info" })for local discovery, team-scoped tokens, and structured cloud error codes (COOLIFY_CLOUD_FORBIDDEN,COOLIFY_CLOUD_UNSUPPORTED). - Local manifest cache —
.coolify/manifest.jsonsync viamanifest({ action: "sync" }), best-effort auto-hooks on app/service/DB mutations, and_meta.manifestWarningwhen the cache is stale. - Server branding — MCP list icon via
serverInfo.icons(embedded data URI + jsDelivr CDN entries fromdocs/assets/). - Ops workflows that mirror real incidents — a single
system.infrastructure_overviewcall for the big picture, fuzzyresource.findwhen you only remember a name or domain,diagnose.app/diagnose.serverfor a specific suspect, anddiagnose.scanwhen you just know something is wrong fleet-wide. - Deploy lifecycle agents can drive — start/stop/restart, force rebuild,
deployment.watchwith bounded backoff,deployment.logsfor builds, boundedapplication.logs, and runtime follow with idle/overall timeouts. - Full workload CRUD — create, inspect, update, delete, and operate applications, services, and databases; discover live one-click IDs with
service.list-types. - Recipes and guided setup — create git apps, app-plus-database stacks, and one-click services; run
setup.preflight,setup.wire, orsetup.resume; install four matching IDE workflow skills. - Safety by default, not by convention — emergency mutations require an explicit
confirm: true; sensitive keys (password,token,secret,private,env) render as***unless you opt in withreveal: true. - Agent-friendly failure modes — every error is a parseable envelope with a
code, a humanmessage, andrecoveryHints; transient network/429/5xx failures retry automatically with exponential backoff. - Broad client coverage out of the box — Cursor, VS Code / GitHub Copilot, Claude Desktop, Claude Code, Windsurf, and 15+ more via the install configurator.
🏗️ How it works
MCP client (Cursor / Claude / VS Code / …)
│ stdio MCP
▼
awesome-coolify-mcp (19 tools + action discriminator)
│ optional ~/.coolify-mcp/instances.json resolution
│ HTTPS + Bearer token
▼
Coolify REST API 4.1.x (servers · projects · applications · services · databases)
The server itself is intentionally boring: it holds no long-lived state and never touches your IDE's config files. Your MCP host (Cursor, Claude, VS Code, …) injects COOLIFY_URL and COOLIFY_TOKEN through its MCP config's env block — or you register named instances in ~/.coolify-mcp/instances.json via the instance tool. The process reads credentials from its environment (or the registry) and forwards authenticated requests to your Coolify instance over HTTPS.
🚀 Quick start
Prerequisites
- Node.js 24+ (Active LTS; CI uses Node 24)
- A self-hosted Coolify instance on 4.1.x
- An API token from Coolify → Keys & Tokens (authorization docs)
Run it directly with npx — no global install needed:
npx -y awesome-coolify-mcp
Wire the two required environment variables into your MCP host (see Install for every client). Once connected, a minimal smoke test looks like this:
meta({ action: "version" }) // server identity — no Coolify call
system({ action: "verify" }) // authenticate + connectivity check
system({ action: "infrastructure_overview" }) // servers, projects, apps, services, DBs at a glance
[!NOTE] Multi-instance users: register each Coolify instance first with
instance({ action: "add", name, url, token }), then callsystem({ action: "verify" }). Single-instance setups can skip the registry and useCOOLIFY_URL/COOLIFY_TOKENin MCP env.
[!IMPORTANT] Emergency actions (
stop_all,redeploy_project,restart_project) requireconfirm: true. Call them withoutconfirmfirst — you'll get awould_affectpreview and no mutation runs. Only passreveal: truewhen you genuinely need plaintext secrets back.
📦 Install
There are three equally supported paths — pick whichever fits your workflow.
1. One-click deeplink
Best when you already have your Coolify URL and token handy. Placeholder credentials work fine too — you'll be prompted to fill them in, or you can swap them afterwards.
Both editors implement a protocol handler that reads a JSON server configuration straight out of the URL:
| Client | Scheme | Encoding |
|---|---|---|
| Cursor | cursor://anysphere.cursor-deeplink/mcp/install?name=…&config=… (mirrored at https://cursor.com/en/install-mcp?… for a friendlier landing page) |
config is base64-encoded JSON |
| VS Code / Copilot | vscode:mcp/install?name=…&config=… |
config is URL-encoded JSON |
Clicking the button opens your editor, shows the server it's about to add, and lets you review or edit the command/env before accepting — nothing is installed silently.
2. Install configurator (GitHub Pages)
Use the browser configurator to type in your real COOLIFY_URL / COOLIFY_TOKEN and generate a ready-to-paste snippet for your exact client — JSON, TOML, or YAML depending on what that client expects.
Everything runs client-side in your browser. Your token is never sent to a backend, logged, or stored anywhere but the config file you paste it into.
3. Manual MCP config
Paste this into your host's MCP configuration file. Cursor example (~/.cursor/mcp.json for global, or .cursor/mcp.json in a project):
{
"mcpServers": {
"awesome-coolify-mcp": {
"command": "npx",
"args": ["-y", "awesome-coolify-mcp"],
"env": {
"COOLIFY_URL": "https://coolify.example.com",
"COOLIFY_TOKEN": "YOUR_COOLIFY_API_TOKEN",
"COOLIFY_VERIFY_SSL": "true",
"COOLIFY_MCP_LOG": "info"
}
}
}
}
A ready-made copy-paste template also lives at docs/mcp.example.json.
[!TIP] Using Coolify Cloud? Generate a team-scoped token and follow the registry setup in docs/en/cloud.md.
IDE skills (Cursor, Claude Code, Codex)
Install Coolify workflow skills for Cursor, Claude Code, and Codex:
npx skills add clezcoding/awesome-coolify -a cursor -a claude-code -a codex
After MCP install, run setup({ action: "preflight" }) or see the Setup guide for gh preflight, project linkage, and greenfield provisioning.
🖥️ Supported clients
| Client | Config location | Notes |
|---|---|---|
| Cursor | ~/.cursor/mcp.json |
One-click deeplink or manual JSON |
| VS Code / GitHub Copilot | .vscode/mcp.json |
Native inputs prompts for URL/token — no plaintext in the file |
| Claude Desktop | claude_desktop_config.json |
Manual JSON or configurator output today |
| Claude Code | ~/.claude.json or .mcp.json |
stdio via npx -y awesome-coolify-mcp |
| Windsurf | ~/.codeium/windsurf/mcp_config.json |
Same npx + env pattern as Cursor |
The install configurator covers a much wider matrix — OpenCode, Codex CLI, Gemini CLI, Cline, Kilo Code, Goose, LM Studio, Hermes Agent, Kimi Code, Google Antigravity, OpenClaw, and more — with the correct config shape for each.
[!NOTE] Claude Desktop currently uses manual JSON or configurator output.
🔐 Environment variables
| Variable | Required | Default | Description |
|---|---|---|---|
COOLIFY_URL |
yes* | — | Coolify base URL, no trailing slash — e.g. https://coolify.example.com |
COOLIFY_TOKEN |
yes* | — | Bearer API token, scoped to your team |
COOLIFY_VERIFY_SSL |
no | true |
Set to false only for self-signed certs on local/dev instances |
COOLIFY_MCP_LOG |
no | info |
Log verbosity: debug · info · error |
Credentials are read from the process environment (your IDE's MCP env block) or an optional local .env file when running the CLI directly. They are never echoed back inside tool responses.
[!NOTE] With the multi-instance registry (
~/.coolify-mcp/instances.json),COOLIFY_URLandCOOLIFY_TOKENbecome optional — theinstancetool resolves credentials per call. Env vars remain the simplest path for single-instance setups.
☁️ Coolify Cloud
awesome-coolify-mcp works with Coolify Cloud using the same 19 tools — team-scoped tokens, structured cloud error codes (COOLIFY_CLOUD_FORBIDDEN, COOLIFY_CLOUD_UNSUPPORTED), and local instance action cloud-info for discovery.
Run instance({ action: "cloud-info" }) before your first Cloud session — it returns isCloud, resolved url, credential source (registry | env | infer), knownLimits, and a docs link. No live API call.
Full setup, smoke test, and known limits → docs/en/cloud.md
💬 MCP Prompts
Six parameterized workflow prompts return numbered step guidance (English bodies) that orchestrate existing tools. Most arguments are optional — open any prompt without prefill.
| Prompt | Args (all optional unless noted) | Purpose |
|---|---|---|
deploy |
instance?, uuid?, force? |
Deploy an application and monitor until terminal status |
diagnose |
instance?, uuid? |
Investigate app, server, or fleet-wide issues (includes diagnose.analyze) |
new-project |
instance?, name?, server_uuid? |
Create project, environment, and optional server linkage |
incident |
instance?, uuid?, project_uuid? |
Triage with diagnose.analyze, logs, restart, or emergency redeploy |
rollback |
instance?, uuid?, name? |
Preview then confirm-gated deployment.rollback (STOP for human approval) |
maintenance-window |
instance?, uuid?, resource_type |
Guided change window using existing confirm-gated mutations |
Prompt handlers never read .coolify/manifest.json from disk — they steer the agent to resolve UUIDs from manifest or ask the user. Playbooks never auto-set confirm: true.
🧰 Tools reference
Every domain is exposed as one MCP tool with an action discriminator, so your agent's tool list stays short while the capability surface stays wide.
system({ action: "health" })
application({ action: "deploy", uuid: "<app-uuid>", wait: false })
deployment({ action: "watch", deployment_uuid: "<deployment_uuid>", timeout: 300 })
emergency({ action: "stop_all", confirm: true })
🖥️ system — connectivity & overview
Your first call in any session: is Coolify reachable, and what does the fleet look like right now?
| Action | Purpose |
|---|---|
health |
Verify Coolify API reachability |
version |
Coolify instance version string |
verify |
Authenticate; returns connectivity + version in one call |
infrastructure_overview |
Aggregate counts across servers, projects, applications, services, databases |
🏷️ meta — server identity
| Action | Purpose |
|---|---|
version |
awesome-coolify-mcp's own package name + semver — no Coolify call at all |
🔎 resource — discovery
For when you know roughly what you're looking for but not its exact UUID.
| Action | Purpose |
|---|---|
list |
Applications, services, and databases as summary projections, with pagination _meta |
find |
Fuzzy search by name, domain, or IP across servers and resources — ranked, capped at 10 |
🩺 diagnose — investigation
The tool you reach for when something feels wrong but you don't yet know what.
| Action | Purpose |
|---|---|
app |
App status, health, env var count, and recent deployments |
server |
Server resources, domains, and reachability |
scan |
Fleet-wide issues grouped by severity — the "what's on fire" button |
logs |
Resolve an application, return triage context, and optionally include bounded runtime or deployment logs |
analyze |
Log Brain — rule-based pattern triage on runtime (and optional build) logs; advisory-only (crash_loop, OOM, etc.) |
Coolify MCP questions
How do I add Coolify MCP to Claude Code?
Run claude mcp add awesome-coolify -- npx -y awesome-coolify-mcp in your terminal. Add --scope user to make it available in every project.
How do I add Coolify MCP to Cursor?
Open ~/.cursor/mcp.json and add the server under mcpServers, using the Cursor config shown in the install section above.
What tools does Coolify MCP provide?
It exposes 45 tools, including health, version, verify, infrastructure_overview, list.
What can I do with this MCP server?
You can verify connectivity, discover infrastructure, create workloads, deploy, follow logs, diagnose incidents, and run emergency operations across Coolify instances.
Is it safe to use with sensitive data?
Yes, the server includes default secret masking for passwords and tokens, and requires explicit confirmation for destructive emergency actions.