awesome-coolify-mcp

📋 Table of contents

• Overview

• Why awesome-coolify-mcp

• Features

• How it works

• Quick start

• Install

  • 1. One-click deeplink

  • 2. Install configurator

  • 3. Manual MCP config

• Coolify Cloud

• Supported clients

• Environment variables

• Tools reference

• Safety model

• Structured errors & retries

• Example agent workflows

• Status today

• Coming soon

• Local development

• Links

Related MCP server: coolify-mcp

🔭 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 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 domain tools with an action field:

application({ action: "deploy", uuid: "<app-uuid>", wait: true })
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.

🆚 Why awesome-coolify-mcp

Today, the focus covers day-2 operations plus growing infrastructure CRUD: verify connectivity, discover your fleet, deploy, pull logs, diagnose incidents, run gated emergency ops — and manage SSH keys, servers, projects, and environments. Full CRUD for applications, services, and databases is next — see Coming soon.

✨ Features

• Action-based tools across 14 domains — call application({ action: "deploy", uuid }) instead of hunting through dozens of tool names. Domains span ops (system, resource, diagnose, application, deployment, service, database, emergency), infrastructure CRUD (private_key, server, project, environment), plus docs and meta.

• Ops workflows that mirror real incidents — a single system.infrastructure_overview call for the big picture, fuzzy resource.find when you only remember a name or domain, diagnose.app / diagnose.server for a specific suspect, and diagnose.scan when you just know something is wrong fleet-wide.

• Deploy lifecycle that agents can actually drive — start/stop/restart, deploy with optional wait-and-poll or force rebuild, list/get/cancel deployments, and bounded runtime or build logs that won't blow your context window.

• Service & database lifecycle — start/stop/restart/get, plus service redeploy with an optional fresh image pull.

• 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 with reveal: true.

• Agent-friendly failure modes — every error is a parseable envelope with a code, a human message, and recoveryHints; 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  (14 domain tools + action discriminator)
        │  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; the process reads them from its environment (or an optional local .env when you run it directly from the CLI) and forwards authenticated requests to your Coolify instance over HTTPS.

🚀 Quick start

Prerequisites

• Node.js 22.14+ (CI runs on 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

📦 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:

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.

🖥️ Supported clients

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.

🔐 Environment variables

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.

☁️ Coolify Cloud

awesome-coolify-mcp works with Coolify Cloud using the same 14 tools — team-scoped tokens, structured cloud error codes (COOLIFY_CLOUD_FORBIDDEN, COOLIFY_CLOUD_UNSUPPORTED), and local instance action cloud-info for discovery.

Full setup, smoke test, and known limits → docs/en/cloud.md

🧰 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: true })
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?

🏷️ meta — server identity

🔎 resource — discovery

For when you know roughly what you're looking for but not its exact UUID.

🩺 diagnose — investigation

The tool you reach for when something feels wrong but you don't yet know what.

🚀 application — app operations

📈 deployment — deploy tracking

🧩 service / database — sidecar lifecycle

🌱 Resource environment variables (envs:*)

Manage Coolify runtime configuration on applications, services, and databases through envs:* actions on the existing domain tools — no separate env MCP tool.

Confirm gates: envs:delete and envs:bulk-update always require confirm: true on all three tools. On application only, envs:sync requires confirm: true when applying (dry_run: false, the default) or when prune: true.

Reveal policy: Env values render as *** by default. Pass reveal: true only after the human explicitly asks for plaintext — the agent must not auto-set reveal: true.

envs:sync semantics (application only): Supply exactly one of env_file (local path) or env_content (inline .env text). dry_run: true returns a diff (added, updated, unchanged, removed, optional conflicts) with no API writes; default dry_run: false applies changes. Remote keys missing locally are never deleted unless prune: true (also requires confirm: true). When local and remote values differ, set conflict_policy to overwrite, keep_remote, or abort after asking the human — apply with conflicts and no policy returns COOLIFY_CONFIRM_REQUIRED.

application({ action: "envs:list", uuid: "<app-uuid>" })
application({ action: "envs:sync", uuid: "<app-uuid>", env_file: "./.env", dry_run: true })
application({ action: "envs:sync", uuid: "<app-uuid>", env_content: "API_KEY=EXAMPLE_VALUE\n", confirm: true, conflict_policy: "overwrite" })

💾 Database backups (backup:*)

Configure, list, update, delete, and trigger backup schedules — and inspect execution history — on the existing database tool. No separate backup MCP tool.

Parent identity: All backup actions require the parent database via uuid or name. Schedule-scoped actions (backup:update, backup:delete, backup:now, backup:history) also require scheduled_backup_uuid.

Confirm gates: backup:delete requires confirm: true — otherwise COOLIFY_CONFIRM_REQUIRED. delete_s3 defaults false (config-only delete). When delete_s3: true, deletion still requires confirm: true — purging S3 artifacts is treated as destructive.

Frequency (Pitfall 1): backup:create accepts OpenAPI named presets (every_minute, hourly, daily, weekly, monthly, yearly) or a cron expression. backup:update accepts presets only — passing cron on update returns COOLIFY_VALIDATION_ERROR.

backup:now semantics: Maps to Coolify PATCH with { backup_now: true } on the schedule — no separate trigger endpoint. Requires scheduled_backup_uuid.

Reveal policy: S3-related credentials in backup config responses are masked as *** by default. Pass reveal: true only after the human explicitly asks for plaintext — the agent must not auto-set reveal: true.

Out of scope (v2.x+): Backup execution delete, restore/import from backup, and S3 storage destination CRUD are not available in this release.

database({ action: "backup:list", uuid: "<db-uuid>" })
database({ action: "backup:create", uuid: "<db-uuid>", frequency: "daily", save_s3: false })
database({ action: "backup:now", uuid: "<db-uuid>", scheduled_backup_uuid: "<schedule-uuid>" })
database({ action: "backup:delete", uuid: "<db-uuid>", scheduled_backup_uuid: "<schedule-uuid>", confirm: true })

🔑 private_key — SSH key CRUD

Manage Coolify private keys with PEM content masked by default.

🖧 server — server CRUD & validation

📁 project — project CRUD

🌍 environment — environment CRUD

📚 docs — offline guides

🚨 emergency — high-impact ops (gated)

Reach for these only when you mean it — every action below is behind a confirmation gate.

🛡️ Safety model

Confirmation gate

Destructive emergency actions follow a strict two-step pattern:

1. Call with confirm omitted or false → you get back a would_affect preview and error code COOLIFY_CONFIRM_REQUIRED — nothing is mutated.

2. Call again with confirm: true → the action actually executes.

Regular app/service/database mutations (start, stop, deploy, …) are not behind this gate — they simply follow Coolify's own API semantics, since they're scoped to one resource rather than your whole fleet.

Environment variables: envs:delete and envs:bulk-update require confirm: true on application, service, and database. envs:sync apply (dry_run: false) and envs:sync with prune: true require confirm: true on application only. dry_run: true sync previews never mutate.

Secret masking

• Keys matching password, token, secret, private, or env render as *** by default in tool output.

• Pass reveal: true only when you explicitly need plaintext — for example, to copy an env var into another system. Ask the human first before setting reveal: true on any envs:* call.

• Log line bodies are not masked. Treat raw logs like you would any other sensitive output: don't paste them into long-lived agent memory or public tickets.

⚠️ Structured errors & retries

Every API failure comes back as a parseable envelope your agent can reason about, instead of a raw stack trace:

{
  "code": "COOLIFY_401",
  "message": "Unauthorized — invalid or expired API token",
  "recoveryHints": [
    "Verify the token in Coolify UI → Keys & Tokens",
    "Ensure the token has the required team permissions"
  ],
  "httpStatus": 401
}

Transient failures (HTTP 429, 5xx, or network errors) retry automatically up to 3 times with exponential backoff (1s → 2s → 4s) before giving up and returning the error to your agent.

💬 Example agent workflows

"Is my Coolify reachable, and what do I have?"

system({ action: "verify" })
system({ action: "infrastructure_overview" })
resource({ action: "list" })

"Find the nginx app, deploy it, then show me the logs."

resource({ action: "find", query: "nginx" })
application({ action: "deploy", uuid: "<uuid>", wait: true })
application({ action: "logs", uuid: "<uuid>" })

"Something feels wrong across the fleet."

diagnose({ action: "scan" })
diagnose({ action: "app", uuid: "<suspect>" })
diagnose({ action: "server", uuid: "<server>" })

"Emergency: stop everything, but let me see the blast radius first."

emergency({ action: "stop_all" })                 // preview — would_affect, no mutation
emergency({ action: "stop_all", confirm: true })  // execute

✅ Status today

The server is stable and actively used for day-2 operations against real Coolify 4.1.x instances:

Service/database log tailing is temporarily on hold — Coolify 4.1.x's REST API doesn't expose a /services/{uuid}/logs or /databases/{uuid}/logs endpoint yet (the fix has merged upstream but isn't backported to 4.1.x). It'll ship the moment the endpoint is reachable, with no half-working stub in the meantime.

🔮 Coming soon

The next milestone focuses on creation for workloads, not just infrastructure scaffolding — turning awesome-coolify-mcp into a tool that can stand up new applications, services, and databases from scratch, not only manage what already exists. Planned areas, roughly in order of priority:

• Full CRUD for applications, services, and databases — create, update, and delete, not just start/stop/deploy

• Environment variable management — read, write, bulk-sync from a local .env

• One-click services — full service catalog with compose YAML, storage, and env configuration

• Database backups — schedules, executions, and on-demand triggers

• Scheduled tasks — cron job CRUD, execution history, run-once triggers

• Teams & multi-tenancy — list/get teams and members, per-project scoped tokens

• Cloud provider tokens — Hetzner/DigitalOcean provisioning credentials (SSH keys already shipped)

• GitHub App integration — repo/branch discovery, enterprise URLs

• Claude Desktop .mcpb packaging — true one-click install, no manual JSON

• Deeper observability — container-level metrics, Traefik insight, live event streams, log search

Have a use case that isn't listed? Open an issue — the roadmap is shaped by what the community actually runs into.

🛠️ Local development

git clone https://github.com/clezcoding/awesome-coolify.git
cd awesome-coolify
npm install
npm run build    # tsup → dist/
npm test         # vitest
npm run dev      # watch mode

Logs go to stderr only — stdout is reserved exclusively for the MCP protocol.

The maintainer publish flow (build → pack --dry-run → publish) is documented in CONTRIBUTING.md.

🔗 Links