coolify-mcp

A TypeScript MCP server that drives a self-hosted Coolify instance. Full REST CRUD, deploy/watch, and a flag-gated host-ops tier (SSH + Docker + psql) for live log streaming and ad-hoc access.

Quick Start

# Install from GitHub (team members with repo access)
npm install -g github:jimrarras/coolify-mcp
# …or run ad-hoc without installing:  npx -y github:jimrarras/coolify-mcp doctor
#
# The published build is a single self-contained bundle with ZERO native/runtime
# dependencies — it installs on any machine with no C/C++ toolchain and runs no
# install scripts. No flags needed.

# Copy and fill in env
cp .env.example .env
$EDITOR .env

# Run (API tier only)
coolify-mcp

# Run with host-ops (SSH access) enabled
coolify-mcp --enable-host-ops

# Run with destructive actions allowed (requires confirm:true per-call)
coolify-mcp --enable-host-ops --allow-destructive

Guided setup (recommended)

Two commands take you from installed to working:

coolify-mcp init      # one-time interactive wizard — writes ~/.coolify-mcp/config.json
coolify-mcp doctor    # verify the setup any time, with a specific fix for each failure

Prefer not to touch a config file? The zero-file env-var mode (just COOLIFY_BASE_URL + COOLIFY_TOKEN) still works for the API tier — init is for a guided setup that also wires up host-ops.

What init asks

1. Base URL + API token — validated live against your instance before continuing. The token must be <id>|<secret> with scope write + read:sensitive.

2. Enable host-ops? If yes, it resolves the SSH control host. On a standard single-server install Coolify reports the host's IP as host.docker.internal, so auto-detect can't match it — init then lists your servers and asks you to pick the control host (anti-hijack: it won't silently guess). It substitutes your baseUrl host as the reachable SSH address.

3. It then auto-discovers a working SSH key — it scans ~/.ssh, tries each OpenSSH key against the host, and prompts (masked) for a passphrase if the key needs one. (A PuTTY .ppk is detected and you're told to export an OpenSSH key first.)

4. It shows the host's key fingerprint and asks you to confirm before pinning it.

5. Enable query_coolify_db? If yes, it prints ready-to-run CREATE ROLE … GRANT … REVOKE … SQL (with a generated password) for you to run on your Coolify Postgres.

It writes ~/.coolify-mcp/config.json (backing up any existing one) with secrets as ${ENV} references, never inline — for example:

{
  "defaultInstance": "default",
  "instances": {
    "default": {
      "baseUrl": "https://coolify.example.com",
      "token": "${COOLIFY_TOKEN}",
      "enableHostOps": true,
      "allowDestructive": false,
      "ssh": {
        "keyPath": "/home/you/.ssh/id_ed25519",
        "hostServer": "<control-server-uuid>",
        "fingerprint": "SHA256:…",
        "passphrase": "${COOLIFY_SSH_KEY_PASSPHRASE}"
      }
    }
  }
}

…then prints the env vars to set (COOLIFY_TOKEN, COOLIFY_SSH_KEY_PASSPHRASE, …) and the MCP-client snippet to paste. Set those env vars in your MCP client's env block (or shell), since the ${ENV} references are expanded at startup.

doctor

doctor runs read-only checks and prints a fix for anything that fails (add --enable-host-ops to include the SSH/DB checks):

$ coolify-mcp doctor --enable-host-ops
── instance: default ──
PASS  api — Coolify 4.1.2 reachable
PASS  control_host — root@coolify.example.com:22 (using baseUrl host)
PASS  ssh — SSH root@coolify.example.com:22 OK
SKIP  db_role — query_coolify_db not configured

It exits non-zero if any check fails, so it's usable as a preflight in scripts.

Add to your MCP client config (e.g. ~/.claude/claude_desktop_config.json):

{
  "mcpServers": {
    "coolify": {
      "command": "coolify-mcp",
      "args": [],
      "env": {
        "COOLIFY_BASE_URL": "https://coolify.example.com",
        "COOLIFY_TOKEN": "<id>|<secret>"
      }
    }
  }
}

Related MCP server: Enhanced Coolify MCP Server

Configuration

1. Zero-file quick start

Set two environment variables and run — no config file needed:

export COOLIFY_BASE_URL="https://coolify.example.com"
export COOLIFY_TOKEN="<id>|<secret>"
coolify-mcp

The token format is <id>|<secret> — both parts required. The id is an integer; the secret is an alphanumeric string.

2. Config file

For multi-instance setups or richer per-instance settings, supply a JSON config file.

File resolution order:

1. --config <path> CLI flag

2. COOLIFY_CONFIG environment variable

3. ~/.coolify-mcp/config.json (auto-discovered if present)

4. Falls back to env-var mode (step 1) if none of the above exists

${ENV} expansion is applied to every string value in the file, including nested ones.
${VAR} — substitutes the environment variable; throws if unset.
${VAR:-default} — uses default when VAR is unset or absent.

Only baseUrl and token are required per instance; everything else is optional and defaults to safe values.

See config.example.json for a full multi-instance example.

3. Host-ops configuration

To enable SSH access, set "enableHostOps": true and provide ssh.keyPath.
The SSH host, user, and port are auto-derived from the Coolify API — no need to set them manually.

Single-server installs (host.docker.internal). Coolify's built-in "localhost" server often reports its ip as host.docker.internal (a Docker-internal alias) that a remote workstation can't SSH to. Two things handle this:

• Select the control host explicitly with ssh.hostServer (its UUID or name) — required because a non-matching server is not auto-selected (anti-hijack). When the selected server's ip is a non-routable alias, coolify-mcp automatically substitutes the baseUrl host (which is reachable and operator-trusted).

• Override the SSH address with ssh.host when even the baseUrl host isn't SSH-reachable (e.g. it's behind a proxy/CDN) — set it to the server's real IP/hostname.

Minimal host-ops config for a standard single-server install:

"ssh": { "keyPath": "~/.ssh/id_ed25519", "hostServer": "<server-uuid-or-name>" }

Add "host": "<reachable-ip>" if baseUrl isn't directly SSH-reachable.

"ssh": {
  "keyPath": "~/.ssh/id_ed25519"
}

Tilde (~) is expanded to the home directory. Optional overrides:

SSH host-key verification is fail-closed. The server will not connect unless the key presented by the remote host matches either ssh.fingerprint (SHA-256, from ssh-keyscan <host> | ssh-keygen -lf -) or the appropriate entry in ssh.knownHostsPath / ~/.ssh/known_hosts. A missing or non-matching entry is an immediate connection refusal. Note: known_hosts matching is literal — wildcard (*.example.com) and hashed (|1|...) entries are not matched; use ssh.fingerprint or a literal host line for those hosts.

Threat-model note (host-ops trusts the Coolify API). The SSH host/user/port are derived from the Coolify API (GET /servers). A compromised Coolify API could therefore influence which host the MCP connects to — but this is bounded by the fail-closed host-key verification above (a redirect to an untrusted host is refused). For the strongest assurance set ssh.fingerprint to pin the control host's key regardless of known_hosts. Connections to remote managed servers run via docker -H ssh://… on the Coolify host, so that hop is governed by the Coolify host's own SSH trust store rather than this client's.

4. query_coolify_db — read-only DB role

Set db.readonlyUser per instance to enable the query_coolify_db tool. The in-code SQL blocklist and output redaction are best-effort defense-in-depth only — they cannot make arbitrary free-form SQL safe. You MUST provision the role so PostgreSQL enforces the constraints:

CREATE ROLE coolify_ro LOGIN PASSWORD '...' NOSUPERUSER NOCREATEDB NOCREATEROLE;
GRANT CONNECT ON DATABASE coolify TO coolify_ro;
GRANT USAGE ON SCHEMA public TO coolify_ro;
GRANT SELECT ON ALL TABLES IN SCHEMA public TO coolify_ro;   -- omit sensitive tables/columns you don't want exposed
REVOKE EXECUTE ON ALL FUNCTIONS IN SCHEMA public FROM coolify_ro;  -- blocks adminpack/dblink/file fns
-- do NOT grant pg_read_server_files / pg_write_server_files / pg_execute_server_program / superuser

Treat query_coolify_db output as "whatever this role may SELECT" — redaction reduces incidental leakage but is not guaranteed.

5. Multi-instance + per-call instance selector

A single coolify-mcp process can drive multiple Coolify instances simultaneously.
Every tool exposes an optional instance argument; omit it to use the default instance.

// config.json
{
  "defaultInstance": "prod",
  "instances": {
    "prod":    { "baseUrl": "https://coolify.prod.example.com",    "token": "${PROD_TOKEN}" },
    "staging": { "baseUrl": "https://coolify.staging.example.com", "token": "${STAGING_TOKEN}" }
  }
}

Example tool call routing to the non-default instance:

{ "tool": "list_resources", "arguments": { "instance": "staging", "type": "applications" } }

enableHostOps/allowDestructive are per-instance — you can allow destructive actions on staging while keeping them blocked on prod.

6. CLI flags + back-compat

When no config file is used, the legacy flags and environment variables still work and map onto the synthesized default instance:

When a config file is loaded, --enable-host-ops and --allow-destructive are ignored (a warning is printed); per-instance gating comes from the file.

Token Scope Guidance

Coolify tokens carry full-account permissions. For read-only use (monitoring, querying), prefer creating a dedicated read-only token in Coolify's settings if the feature is available for your version. For write operations, use a token scoped to the team/project you intend to manage. Never share the same token across environments.

Tools

Tools are grouped by tier. Tier determines what flags must be set for the tool to be registered and callable.

Destructive host actions (docker rm/rmi/stop/kill/prune/exec) additionally require --allow-destructive and confirm: true. The host tier is root-level read access by design: read-only docker_op actions (inspect, logs, …) and read_host_file can surface container configuration including environment variables/secrets — treat their output as sensitive. docker_args rejects shell metacharacters and {} template braces, but plain docker inspect <container> still returns that container's full config; only enable --enable-host-ops for trusted callers.

Deploy

Resources (Applications, Databases, Services)

Environment Variables

Projects

Servers & Keys

Logs

Host Ops

Security Notes

Never-Exposed Endpoints (Lockout Policy)

The following Coolify API endpoints are intentionally never exposed as tools, because calling them from an automated agent risks locking out all access to the Coolify UI:

• GET /enable — enables Coolify

• GET /disable — disables Coolify

• POST /mcp/enable — enables Coolify's own MCP endpoint

• POST /mcp/disable — disables Coolify's own MCP endpoint

• IP-allowlist mutation endpoints

Destructive Operations

All destructive operations follow a deny-by-default, double-confirmation model:

1. The server must be started with --allow-destructive.

2. Each individual call must include confirm: true in its arguments.

3. You can pass dry_run: true to preview what would be executed without performing it.

Host-Ops Tier

When enableHostOps: true is set for an instance (or --enable-host-ops in env mode), the server opens an SSH connection to the Coolify host on first use. Commands run as the configured SSH user (typically root). File access is restricted to /data/coolify/** prefixes. SQL access is restricted to read-only SELECT statements.

SSH host-key verification is fail-closed. The server refuses to connect unless the key presented by the remote host matches either ssh.fingerprint (SHA-256, from ssh-keyscan <host> | ssh-keygen -lf -) or the appropriate entry in ssh.knownHostsPath / ~/.ssh/known_hosts. A missing or non-matching entry is an immediate connection refusal.

Development

npm install
npm test              # vitest
npm run build         # esbuild -> single self-contained dist/cli/index.js bundle
npm run probe         # scripts/probe.ts (requires COOLIFY_TEST_BASE_URL / COOLIFY_TEST_TOKEN)

Note — dist/ is committed. npm run build bundles the CLI, the MCP server, and all runtime deps (ssh2, the MCP SDK, …) into a single dist/cli/index.js via esbuild, with ssh2's native bindings externalized (it falls back to pure-JS crypto). The result has zero runtime dependencies, so npm install github:… compiles nothing and runs no install scripts on the user's machine. Because no build runs at install time, the bundle is checked into git: run npm run build and commit the updated dist/cli/index.js whenever you change anything under src/. (Runtime libs live in devDependencies since they're bundled, not installed by consumers.)

License

MIT