Operate Coolify from your coding agent.
Verify connectivity, discover infrastructure, create workloads, deploy, follow logs, diagnose incidents, and run gated emergency ops โ across one or many self-hosted or Cloud instances โ
straight from Cursor, Claude, VS Code, Windsurf, or any MCP-speaking agent.
One click installs with placeholder credentials โ see Install for the full walkthrough, or use the browser configurator to fill in real values safely.
---
## ๐ Table of contents
- [Overview](#-overview)
- [Why awesome-coolify-mcp](#-why-awesome-coolify-mcp)
- [Features](#-features)
- [How it works](#-how-it-works)
- [Quick start](#-quick-start)
- [Install](#-install)
- [1. One-click deeplink](#1-one-click-deeplink)
- [2. Install configurator](#2-install-configurator-github-pages)
- [3. Manual MCP config](#3-manual-mcp-config)
- [Coolify Cloud](#%EF%B8%8F-coolify-cloud)
- [Supported clients](#-supported-clients)
- [Environment variables](#-environment-variables)
- [MCP Prompts](#-mcp-prompts)
- [Tools reference](#-tools-reference)
- [Safety model](#-safety-model)
- [Structured errors & retries](#-structured-errors--retries)
- [Example agent workflows](#-example-agent-workflows)
- [Status today](#-status-today)
- [Coming soon](#-coming-soon)
- [Local development](#-local-development)
- [Links](#-links)
---
## ๐ญ Overview
Self-hosted [Coolify](https://coolify.io) 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`](https://github.com/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:
```js
application({ action: "deploy", uuid: "", wait: false })
deployment({ action: "watch", 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 is `system`, `meta`, `resource`, `diagnose`, `application`, `emergency`, `deployment`, `service`, `database`, `private_key`, `instance`, `manifest`, `server`, `project`, `environment`, `docs`, `recipe`, `setup`, and `intelligence`.
- **Multi-instance registry & routing** โ register every Coolify instance you own in `~/.coolify-mcp/instances.json` via the `instance` tool; 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.json` sync via `manifest({ action: "sync" })`, best-effort auto-hooks on app/service/DB mutations, and `_meta.manifestWarning` when the cache is stale.
- **Server branding** โ MCP list icon via `serverInfo.icons` (embedded data URI + jsDelivr CDN entries from `docs/assets/`).
- **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 agents can drive** โ start/stop/restart, force rebuild, `deployment.watch` with bounded backoff, `deployment.logs` for builds, bounded `application.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`, or `setup.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 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](https://clezcoding.github.io/awesome-coolify/install.html).
---
## ๐๏ธ How it works
```text
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](https://coolify.io/docs/api-reference/authorization))
Run it directly with `npx` โ no global install needed:
```bash
npx -y awesome-coolify-mcp
```
Wire the two required environment variables into your MCP host (see [Install](#-install) for every client). Once connected, a minimal smoke test looks like this:
```js
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 call `system({ action: "verify" })`. Single-instance setups can skip the registry and use `COOLIFY_URL` / `COOLIFY_TOKEN` in MCP env.
> [!IMPORTANT]
> Emergency actions (`stop_all`, `redeploy_project`, `restart_project`) require `confirm: true`. Call them **without** `confirm` first โ you'll get a `would_affect` preview and no mutation runs. Only pass `reveal: true` when 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.
How these links work (click to expand)
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](https://clezcoding.github.io/awesome-coolify/install.html)** 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):
```json
{
"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`](https://github.com/clezcoding/awesome-coolify/blob/HEAD/docs/mcp.example.json).
> [!TIP]
> Using [Coolify Cloud](https://app.coolify.io)? Generate a **team-scoped** token and follow the registry setup in [docs/en/cloud.md](https://github.com/clezcoding/awesome-coolify/blob/HEAD/docs/en/cloud.md).
### IDE skills (Cursor, Claude Code, Codex)
Install Coolify workflow skills for Cursor, Claude Code, and Codex:
```bash
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](https://github.com/clezcoding/awesome-coolify/blob/HEAD/docs/en/setup.md)** 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](https://clezcoding.github.io/awesome-coolify/install.html)** 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_URL` and `COOLIFY_TOKEN` become optional โ the `instance` tool resolves credentials per call. Env vars remain the simplest path for single-instance setups.
---
## โ๏ธ Coolify Cloud
**awesome-coolify-mcp** works with [Coolify Cloud](https://app.coolify.io) 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](https://github.com/clezcoding/awesome-coolify/blob/HEAD/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.
```js
system({ action: "health" })
application({ action: "deploy", uuid: "", wait: false })
deployment({ action: "watch", 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.) |
### ๐ `application` โ app operations
| Action | Purpose |
|--------|---------|
| `get` | Detailed application configuration |
| `start` / `stop` / `restart` | Container lifecycle control |
| `deploy` | Trigger a deploy with optional `force` rebuild; use `wait: false` + `deployment.watch` (recommended) or legacy `wait: true` poll |
| `logs` | Bounded runtime logs, or bounded follow mode with idle and overall timeouts |
| `envs:list` / `envs:get` | List or fetch env vars (values masked as `***` unless `reveal: true`) |
| `envs:create` / `envs:update` | Create or update individual env vars (supports `is_preview`, `is_literal`, `is_multiline`, `is_shown_once`) |
| `envs:delete` | Delete one env var โ **requires `confirm: true`** |
| `envs:bulk-update` | Patch many env vars at once โ **requires `confirm: true`** |
| `envs:sync` | Diff/apply a local `.env` file or inline content โ **application only**; see [Resource env vars](#-resource-environment-variables-envs) |
| `envs:promote` | Compare and promote env vars between two applications in the **same Coolify instance** (product name: **env.promote**); preview by default โ see [Resource env vars](#-resource-environment-variables-envs) |
### ๐ `deployment` โ deploy tracking
| Action | Purpose |
|--------|---------|
| `list` | Deployments for a given application |
| `get` | Status, commit, and timing details for one deployment |
| `watch` | Poll until terminal with bounded timeout, backoff, and jitter |
| `cancel` | Cancel an in-flight deployment cleanly |
| `logs` | Bounded deployment build logs by deployment UUID, or newest deployment for an application |
| `preflight` | **Advisory read-only** deploy risk check: `instance_health`, `env_completeness`, `recent_deployment_failures`, `dns_readiness` โ `risk_score` / `risk_level`; env values masked; no live DNS probes |
| `rollback` | **Confirm-gated** recovery to prior successful `finished` deployment when the newest deployment is already `finished`; errors with `COOLIFY_ROLLBACK_UNAVAILABLE` when only one successful deployment exists โ git apps pin `git_commit_sha` via `updateApplication` then `triggerDeploy`; preview without `confirm: true` |
### ๐ก๏ธ Deploy guard (`preflight` + `rollback`)
| Action | Safety |
|--------|--------|
| `preflight` | Read-only โ never calls deploy/mutate APIs; `advisory: true`; `blocking` when risk is critical or a deploy is in progress |
| `rollback` | Two-step like emergency ops: omit `confirm` โ `COOLIFY_CONFIRM_REQUIRED` + `rollback_target` preview (prior successful `finished`, not the current tip when already finished); `confirm: true` โ composite pin+deploy (no dedicated Coolify rollback REST endpoint) |
```js
deployment({ action: "preflight", uuid: "" })
// risk acceptable โ follow recommended_actions to application.deploy
deployment({ action: "rollback", uuid: "" }) // preview
deployment({ action: "rollback", uuid: "", confirm: true, wait: true })
```
### โฑ๏ธ Watch โ bounded deploy monitoring
After `application.deploy` with `wait: false`, call `deployment.watch` โ do not loop `deployment.get` manually.
| Behavior | Detail |
|----------|--------|
| Default timeout | **300 seconds** |
| Poll interval | Starts at **3s**, caps at **30s** with equal-jitter backoff |
| Timeout recovery | Re-call `deployment.watch` with the same `deployment_uuid` (raise `timeout` for slow builds) |
| Failed / cancelled | Tool returns a clear error โ **do not treat as success** |
| Legacy | `application.deploy wait:true` still works but is back-compat only; prefer watch |
```js
application({ action: "deploy", uuid: "", wait: false })
deployment({ action: "watch", deployment_uuid: "", timeout: 300 })
```
The shipped IDE skill packs use this same bounded watch flow and document timeout recovery.
### ๐งฉ `service` / `database` โ sidecar lifecycle
| Tool | Actions |
|------|---------|
| `service` | `get`, `start`, `stop`, `restart`, `deploy`, `create` (one-click type XOR compose), `update`, `delete`, `delete_preview`, `envs:list`, `envs:get`, `envs:create`, `envs:update`, `envs:delete`, `envs:bulk-update` |
| `database` | `get`, `start`, `stop`, `restart`, `create` (8 engines), `update`, `delete`, `delete_preview`, `envs:list`, `envs:get`, `envs:create`, `envs:update`, `envs:delete`, `envs:bulk-update`, `backup:create`, `backup:list`, `backup:update`, `backup:delete`, `backup:now`, `backup:history` |
### ๐ณ `recipe` โ multi-resource orchestration
One MCP call to stand up common workload patterns โ application + database wiring, git apps, or validated one-click services.
| Action | Purpose |
|--------|---------|
| `create-git-app` | Create a git-backed application with local `build_pack` detection (`Dockerfile` / `Dockerfile.*` glob) |
| `create-app-db` | Create a database + application and wire `DATABASE_URL` (or custom `env_key`) between them |
| `create-one-click` | Create a one-click service after validating `type` against the live service-templates catalog |
| `recommend` | **Advisory** stack suggestion from the live service-templates catalog โ never creates resources |
**Safety:** Recipe creates are intentional โ **no confirm gate**. No dry-run / preview. Partial failure does **not** auto-rollback; created UUIDs are returned in `error.data`. Connection strings are masked unless `reveal: true`. `recommend` is read-only / advisory.
```js
recipe({ action: "create-git-app", server_uuid, git_repository, git_branch, repo_path: "/path/to/repo" })
recipe({ action: "create-app-db", server_uuid, app_name, db_name, db_engine: "postgresql" })
recipe({ action: "create-one-click", server_uuid, type: "gitea" })
recipe({ action: "recommend", stack: "Next.js + Postgres" })
```
Also use `service.list-types` to discover valid one-click type IDs before `create-one-click`.
### ๐ฑ 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.
| Tool | `envs:*` actions | Notes |
|------|------------------|-------|
| `application` | `envs:list`, `envs:get`, `envs:create`, `envs:update`, `envs:delete`, `envs:bulk-update`, `envs:sync`, `envs:promote` | Only tool with local `.env` sync and cross-app env promote |
| `service` | `envs:list`, `envs:get`, `envs:create`, `envs:update`, `envs:delete`, `envs:bulk-update` | No sync โ use `application` for `.env` diff/apply |
| `database` | `envs:list`, `envs:get`, `envs:create`, `envs:update`, `envs:delete`, `envs:bulk-update` | **`is_preview` is not supported** on database env vars (Coolify OpenAPI gap) |
**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`. `envs:promote` requires `confirm: true` when applying (`dry_run: false`).
**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`.
**`envs:promote` semantics (application only, same instance):** Product docs may say **env.promote**; the implemented action is `application.envs:promote`. Compare env vars between `source_uuid` and `target_uuid` (two applications in one Coolify instance โ no cross-instance fan-out). Default `dry_run: true` returns preview buckets (`only_in_source`, `only_in_target`, `value_mismatches`) plus structured `promotion_suggestions` with follow-up tool/action hints; values are masked unless `reveal: true`. Applying copies into the target requires `confirm: true`. Default `conflict_policy` is `keep_remote` โ mismatched target keys are skipped unless the human opts into `overwrite` or `abort`.
```js
application({ action: "envs:list", uuid: "" })
application({ action: "envs:sync", uuid: "", env_file: "./.env", dry_run: true })
application({ action: "envs:sync", uuid: "", env_content: "API_KEY=EXAMPLE_VALUE\n", confirm: true, conflict_policy: "overwrite" })
application({ action: "envs:promote", source_uuid: "", target_uuid: "", dry_run: true })
application({ action: "envs:promote", source_uuid: "", target_uuid: "", dry_run: false, confirm: true, conflict_policy: "keep_remote" })
```
### ๐พ 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.
| Action | Purpose |
|--------|---------|
| `backup:create` | Create a backup schedule (frequency required; optional S3, retention, `backup_now: true`) |
| `backup:list` | List backup schedules for a database |
| `backup:update` | Update schedule fields (frequency, retention, S3 flags) |
| `backup:delete` | Remove a schedule โ **requires `confirm: true`** |
| `backup:now` | Trigger an immediate backup run |
| `backup:history` | List executions for a schedule (status, timestamps, size) |
**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.
```js
database({ action: "backup:list", uuid: "" })
database({ action: "backup:create", uuid: "", frequency: "daily", save_s3: false })
database({ action: "backup:now", uuid: "", scheduled_backup_uuid: "" })
database({ action: "backup:delete", uuid: "", scheduled_backup_uuid: "", confirm: true })
```
### ๐ `private_key` โ SSH key CRUD
Manage Coolify private keys with PEM content masked by default.
| Action | Purpose |
|--------|---------|
| `list` / `get` | List or fetch a key (PEM masked unless `reveal: true`) |
| `create` / `update` | Add or rotate SSH keys |
| `delete` / `delete_preview` | Remove a key, or preview dependents before delete |
### ๐ง `server` โ server CRUD & validation
| Action | Purpose |
|--------|---------|
| `get` | Server details, domains, and reachability |
| `create` / `update` | Register or reconfigure a server |
| `validate` | Trigger Coolify's server validation check |
| `delete` / `delete_preview` | Remove a server, or preview dependents first |
### ๐ `project` โ project CRUD
| Action | Purpose |
|--------|---------|
| `list` / `get` | Discover or inspect projects |
| `create` / `update` | Stand up or rename projects |
| `delete` / `delete_preview` | Delete a project, or preview blast radius first |
### ๐ `environment` โ environment CRUD
| Action | Purpose |
|--------|---------|
| `list` / `get` | List or inspect environments inside a project |
| `create` | Add a new environment to a project |
| `delete` / `delete_preview` | Remove an environment, or preview dependents first |
### ๐ `docs` โ offline guides
| Action | Purpose |
|--------|---------|
| `search` | Search a bundled, curated Coolify troubleshooting index โ not a live web fetch, so it works offline and can't be used as an external fetch vector |
### ๐จ `emergency` โ high-impact ops (gated)
Reach for these only when you mean it โ every action below is behind a confirmation gate.
| Action | Purpose |
|--------|---------|
| `stop_all` | Stop every running application, fleet-wide โ **requires `confirm: true`** |
| `redeploy_project` | Redeploy every app in a project โ **requires `confirm: true`** |
| `restart_project` | Restart every app in a project โ **requires `confirm: true`** |
### ๐๏ธ `instance` โ multi-instance registry
Manage named Coolify instances in `~/.coolify-mcp/instances.json`. Per-call credential resolution โ no cross-instance leakage.
| Action | Purpose |
|--------|---------|
| `list` | List registered instances (tokens masked) |
| `get` | Fetch one instance by name |
| `add` | Register a new instance (`name`, `url`, `token`, optional `type: "cloud"`) |
| `update` | Rotate URL or token for an existing instance |
| `delete` | Remove an instance โ **requires `confirm: true`** |
| `set-default` | Set the default instance for ops without an explicit `instance` param |
| `import-env` | Opt-in: copy `COOLIFY_URL` + `COOLIFY_TOKEN` from process env into the registry |
| `cloud-info` | Local Cloud discovery โ `isCloud`, `url`, `source`, `knownLimits`, docs link (no API call) |
```js
instance({ action: "add", name: "prod", url: "https://coolify.example.com", token: "" })
instance({ action: "list" })
instance({ action: "cloud-info" })
```
### ๐ `manifest` โ local cache
Read/write/sync `.coolify/manifest.json` โ a workspace cache, **not** source of truth. Remote wins on UUID conflict.
| Action | Purpose |
|--------|---------|
| `get` | Read the local manifest file |
| `upsert` | Merge projects/servers/resources into the cache |
| `set` | Replace a manifest section |
| `remove` | Remove a cached resource entry |
| `clear` | Wipe the manifest โ **requires `confirm: true`** |
| `sync` | Reconcile cache against live Coolify API (optional `dry_run`, `prune` with `confirm`) |
| `diff` | Non-destructive diff report โ always safe to run |
| `audit` | **Read-only / advisory** drift audit: severity-tagged `findings[]` with structured remediation hints (which tool/action to call next); optional `diff_support` detail โ never mutates manifest or live state |
```js
manifest({ action: "sync", dry_run: true })
manifest({ action: "diff" })
manifest({ action: "audit" })
```
> [!NOTE]
> `manifest.audit` compares local `.coolify/manifest.json` vs live Coolify inventory for the scoped instance. Findings name follow-up actions such as `manifest.sync` or `manifest.upsert` โ hints are advisory only; nothing auto-heals. Keep using `manifest.diff` for the raw structural reconciliation report.
> Best-effort auto-hooks update the manifest after app/service/DB mutations. Stale UUID 404s elsewhere surface `_meta.manifestWarning` โ run `manifest({ action: "sync" })` to reconcile.
### ๐งญ `setup` โ guided project wiring
| Action | Purpose |
|--------|---------|
| `preflight` | Check GitHub CLI and workspace prerequisites without changing the project |
| `wire` | Link an existing workload or provision a greenfield project, with optional domains, env sync, recipe, manifest, and deploy watch steps |
| `resume` | Continue a paused setup after authentication or another recoverable prerequisite |
`wire` never auto-pushes. The setup flow pauses cleanly when `gh` authentication is missing and resumes from completed steps.
### ๐จ Branding (`serverInfo.icons`)
The MCP server advertises icons in `initialize` via an embedded PNG data URI (primary) and jsDelivr CDN URLs for `mcp-icon-192.png` and `favicon-32.png`. Cursor may still show a letter fallback โ see [maintainer verify record](https://github.com/clezcoding/awesome-coolify/blob/HEAD/docs/assets/cursor-icon-verify.md). Not a Coolify API call.
---
## ๐ก๏ธ 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. `envs:promote` apply (`dry_run: false`) requires `confirm: true` on application; default `conflict_policy` is `keep_remote`.
**Drift & heal (read-only audit, preview-first promote):** `manifest.audit` is advisory-only โ it never writes manifest or live state. `application.envs:promote` (product name **env.promote**) previews by default; values stay masked unless `reveal: true`. Both stay within one Coolify instance per call.
**Deploy guard (advisory preflight, confirm-gated rollback):** `deployment.preflight` is read-only and returns a `risk_score` with four named factors โ no external DNS/HTTP probes. `deployment.rollback` requires `confirm: true` before mutating; git rollbacks PATCH the target commit then POST `/deploy` (MCP composite, not a Coolify rollback API).
### 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.
> [!WARNING]
> Registry files (`~/.coolify-mcp/instances.json`) are written with `0o700` directory and `0o600` file permissions. Tokens are never echoed in tool output unless you explicitly pass `reveal: true`.
---
## โ ๏ธ Structured errors & retries
Every API failure comes back as a parseable envelope your agent can reason about, instead of a raw stack trace:
```json
{
"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
}
```
| Code | Meaning |
|------|---------|
| `COOLIFY_401` | Invalid or missing token |
| `COOLIFY_404` | Resource not found |
| `COOLIFY_422` | Validation error |
| `COOLIFY_500` | Coolify server error |
| `COOLIFY_NETWORK` | Connection failed |
| `COOLIFY_TIMEOUT` | Request timed out |
| `COOLIFY_CONFIRM_REQUIRED` | Emergency preview โ pass `confirm: true` to proceed |
| `COOLIFY_AMBIGUOUS_MATCH` | Name matched multiple resources โ pick a UUID from the ranked list |
| `COOLIFY_CLOUD_FORBIDDEN` | Cloud token or team permission issue (HTTP 403) |
| `COOLIFY_CLOUD_UNSUPPORTED` | Endpoint not available on Coolify Cloud (HTTP 404) |
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?"**
```js
system({ action: "verify" })
system({ action: "infrastructure_overview" })
resource({ action: "list" })
```
**"Find the nginx app, deploy it, then show me the logs."**
```js
resource({ action: "find", query: "nginx" })
application({ action: "deploy", uuid: "", wait: false })
deployment({ action: "watch", deployment_uuid: "", timeout: 300 })
application({ action: "logs", uuid: "" })
```
**"Something feels wrong across the fleet."**
```js
diagnose({ action: "scan" })
diagnose({ action: "app", uuid: "" })
diagnose({ action: "server", uuid: "" })
```
**"Emergency: stop everything, but let me see the blast radius first."**
```js
emergency({ action: "stop_all" }) // preview โ would_affect, no mutation
emergency({ action: "stop_all", confirm: true }) // execute
```
**"Multi-instance: list registered instances and verify each."**
```js
instance({ action: "list" })
system({ action: "verify" })
```
---
## โ Status today
Package **1.1.4** ships **19 tools** and six MCP prompts for Coolify API **4.1.x**:
| Capability | Status |
|------------|--------|
| Verify connectivity + infrastructure overview | โ Shipped |
| Discovery: `resource.list` / `resource.find` | โ Shipped |
| Diagnose: app, server, fleet-wide scan + follow-up hints | โ Shipped |
| Log Brain (`diagnose.analyze`) + playbooks (`incident`, `rollback`, `maintenance-window`) | โ Shipped |
| Deploy lifecycle: start/stop/restart, deploy with wait-mode + force rebuild | โ Shipped |
| Deployment tracking: list / get / cancel | โ Shipped |
| Deployment watch and bounded build logs | โ Shipped |
| Application runtime logs, bounded follow, and `diagnose.logs` | โ Shipped |
| Instance intelligence (`intelligence.scorecard`, `graph`, `impact`, `janitor`, `cleanup`) | โ Shipped |
| Drift & heal (`manifest.audit`, `application.envs:promote` / **env.promote**) | โ Shipped |
| Deploy guard (`deployment.preflight`, `deployment.rollback`) | โ Shipped |
| Application, service, and database CRUD | โ Shipped |
| Dynamic one-click type discovery, recipes, and `recipe.recommend` | โ Shipped |
| Setup wizard and four IDE workflow skills | โ Shipped |
| Emergency ops: stop-all, project redeploy/restart, behind confirm gate | โ Shipped |
| SSH key CRUD (`private_key`) with PEM masking | โ Shipped |
| Server CRUD + validation (`server`) | โ Shipped |
| Project & environment CRUD (`project`, `environment`) | โ Shipped |
| Secret masking with explicit `reveal` opt-in | โ Shipped |
| Structured errors, recovery hints, automatic retries | โ Shipped |
| npm distribution + install configurator for 15+ clients | โ Shipped |
| Multi-instance registry (`instance`, `instances.json`) | โ Shipped |
| Coolify Cloud path (`cloud-info`, team-scoped tokens) | โ Shipped |
| Local manifest sync (`.coolify/manifest.json`, auto-hooks) | โ Shipped |
| Live UAT harness (`npm run uat:live`) | โ Shipped |
| Capability discovery via `system.version` | โ Shipped |
| Deployment build logs via `deployment.logs` | โ Shipped |
> **Capability discovery & build logs:** `system({ action: "version" })` returns `coolifyVersion` (replacing the legacy `version` field), `mcpVersion`, and a `capabilities` map of Coolify 4.1.2 feature flags. For **app triage + bounded runtime tail** in one call, use `diagnose({ action: "logs", mode: "full", uuid: "..." })` โ check `capabilities.diagnose_logs`. For **Log Brain pattern triage**, use `diagnose({ action: "analyze", uuid: "..." })` โ check `capabilities.diagnose_analyze`. For **advisory stack picks from the live catalog**, use `recipe({ action: "recommend", stack: "..." })` โ check `capabilities.recipe_recommend`. For **instance health, dependency graph, impact, and janitor/cleanup**, use `intelligence({ action: "scorecard" | "graph" | "impact" | "janitor" | "cleanup", ... })` โ check `capabilities.intelligence_scorecard` (and sibling `intelligence_*` keys); `cleanup` requires `confirm: true`. For **manifest drift audit** and **cross-app env promote**, use `manifest({ action: "audit" })` and `application({ action: "envs:promote", source_uuid, target_uuid, ... })` โ check `capabilities.manifest_audit` and `capabilities.envs_promote` (MCP composites over existing reads/env CRUD, not Coolify-native REST endpoints). For deployment **build** logs, prefer `deployment({ action: "logs", deployment_uuid: "..." })` (or `application_uuid` to resolve the newest deployment). The `application.logs` path with `deployment_uuid` still works for back-compat. For **runtime** log follow, use `application({ action: "logs", uuid: "...", follow: true })` โ bounded MCP polling until idle or timeout; check `capabilities.application_logs_follow` via `system.version`.
> [!WARNING]
> Coolify 4.1.x does not expose stable service or database log endpoints. This server therefore does not claim or register service/database log actions. Use application runtime logs and deployment build logs until compatible upstream APIs are available.
---
## ๐ฎ Coming soon
Future work stays bounded by verifiable upstream and repository constraints:
- Add service/database logs when compatible Coolify APIs are stable and available.
- Close tracked REST mappings in [`docs/COVERAGE.md`](https://github.com/clezcoding/awesome-coolify/blob/HEAD/docs/COVERAGE.md) where they add useful agent workflows.
- Revisit cross-instance fan-out only with explicit rate-limit and credential-isolation guarantees.
No release date or compatibility promise is attached to these boundaries. Use [GitHub Issues](https://github.com/clezcoding/awesome-coolify/issues) for concrete requests.
---
## ๐ ๏ธ Local development
```bash
git clone https://github.com/clezcoding/awesome-coolify.git
cd awesome-coolify
pnpm install
pnpm run build # tsup โ dist/
pnpm test # vitest
pnpm 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](https://github.com/clezcoding/awesome-coolify/blob/HEAD/.github/CONTRIBUTING.md).
> [!NOTE]
> Maintainers can run live UAT against a real Coolify instance with `npm run uat:live`. See [CONTRIBUTING.md โ Live UAT Harness](https://github.com/clezcoding/awesome-coolify/blob/HEAD/.github/CONTRIBUTING.md#live-uat-harness) for prerequisites and report output โ do not duplicate the runbook here.
---
## ๐ Links
| Resource | URL |
|----------|-----|
| Install configurator | [clezcoding.github.io/awesome-coolify/install.html](https://clezcoding.github.io/awesome-coolify/install.html) |
| Install landing page | [clezcoding.github.io/awesome-coolify/](https://clezcoding.github.io/awesome-coolify/) |
| Example MCP JSON | [docs/mcp.example.json](https://github.com/clezcoding/awesome-coolify/blob/HEAD/docs/mcp.example.json) |
| Brand assets | [docs/assets/](https://github.com/clezcoding/awesome-coolify/blob/HEAD/docs/assets/) |
| Coolify | [coolify.io](https://coolify.io) |
| MCP specification | [modelcontextprotocol.io](https://modelcontextprotocol.io) |
| Issues & feature requests | [GitHub Issues](https://github.com/clezcoding/awesome-coolify/issues) |
| Contributing | [CONTRIBUTING.md](https://github.com/clezcoding/awesome-coolify/blob/HEAD/.github/CONTRIBUTING.md) |
| Changelog | [CHANGELOG.md](https://github.com/clezcoding/awesome-coolify/blob/HEAD/CHANGELOG.md) |
| Security policy | [SECURITY.md](https://github.com/clezcoding/awesome-coolify/blob/HEAD/.github/SECURITY.md) |
| License | [MIT](https://github.com/clezcoding/awesome-coolify/blob/HEAD/LICENSE) |
