MCP server for Coolify v4 · MIT

Let your AI agent run your Coolify. Safely.

List apps, manage environment variables, deploy, restart and read logs from Claude, Cursor, VS Code or Windsurf. Secrets stay masked, every change can be a dry run, and read-only mode is one flag away.

Get started View on GitHub

$ npx -y github:amintt2/coolify-mcp

claude · coolify

Set LOG_LEVEL=debug on the api app. Dry run first.

⏺ set_envs(resource: "api", dry_run: true)

{ "dry_run": true,
  "message": "Dry run: nothing was sent to Coolify.",
  "summary": { "created": 0, "updated": 1, "unchanged": 0 },
  "results": [{ "key": "LOG_LEVEL", "status": "updated",
                "changes": ["value"] }] }

⏺ list_envs(resource: "api", key_filter: "DATABASE")

{ "key": "DATABASE_URL", "value": "post*** (41 chars)" }

Dry run looks right: one key changes, nothing else is touched. Your DATABASE_URL stays masked. Apply it and restart the app?

Install

Your config, ready to paste

Type your Coolify URL, pick your client, copy. Runs with npx straight from GitHub, so there is nothing to install beyond Node.js 20+ and git.

Setup

Create your Coolify token

Two minutes in the Coolify dashboard. Give the token only what you want the agent to be able to do.

Enable API access

In Coolify, open Settings → Advanced and turn on API Access.

If Allowed IPs is set, add the IP of the machine that runs the MCP server (usually your laptop).

Create an API token

Open Keys & Tokens → API tokens and create one. It is scoped to the team you are in.

readListing, env keys, deployments, logs
read:sensitiveEnv values to mask & diff, build logs rec.
writeSet and delete env vars
deployDeploy, start, stop, restart
rootNot needed. Don't.

Paste it into your client

Replace <YOUR_COOLIFY_TOKEN> in the snippet above, or let VS Code prompt for it.

Then ask your agent: “Which of my Coolify apps are unhealthy?” It should call get_version and list_applications.

Only team admins and owners can create write, deploy or read:sensitive tokens.

Why this one

Built for letting an agent near production

Every tool is designed around the question “what if the model gets it wrong?”

Secrets masked by default

Env values come back as post*** (41 chars). Plaintext needs reveal: true from the agent and COOLIFY_ALLOW_REVEAL=1 from you.

Dry run everything

set_envs and delete_env take dry_run and report created / updated / unchanged per key without writing, and without echoing values.

Read-only mode

COOLIFY_READ_ONLY=1 refuses every mutating tool. Tools also carry MCP read-only / destructive hints so clients can ask first.

18 tools

Discovery, env vars, deploys, start / stop / restart, deployment status with build logs, and container logs.

Coolify quirks handled

The bulk env endpoint resets is_literal and is_multiline when omitted. set_envs resends them so your flags survive.

Say “the api app”

Reference resources by uuid, name or part of the domain. Ambiguous matches fail with the candidates listed, never a guess.

Reference

Tools

Anything that takes an application or service accepts a uuid, the exact name, or a unique part of its name or domain.

Discovery 7 tools

get_version

Coolify version, health, API base in use, read-only and reveal flags. Call first when something fails.

read

list_projects

Projects and their environments.

read

list_servers

Servers, IPs, reachability and proxy type.

read

list_applications

Name, uuid, domains, status, git repo and branch, project and environment. Optional filter.

read

get_application

One application's details, with webhook secrets and passwords stripped.

read

list_services

One-click and compose services. Optional filter.

read

list_databases

Standalone databases, without credentials.

read

Environment variables 3 tools

list_envs

Keys, uuids and flags for an app or service; values masked. key_filter, reveal.

read

set_envs

Upsert up to 200 keys in one call with build-time / runtime / preview / literal / multiline flags. dry_run.

write

delete_env

Delete one key; is_preview targets the preview copy. dry_run.

destructive

Lifecycle 5 tools

deploy

Deploy by resource (uuid or name, comma-separated) or by Coolify tag. force rebuilds without cache.

deploy

restart_application

Restart containers without rebuilding; picks up runtime env changes.

deploy

start_application

Start a stopped application. force, instant_deploy.

deploy

stop_application

Stop an application's containers. docker_cleanup.

destructive

restart_service

Restart a service, optionally pulling the latest images first.

deploy

Observability 3 tools

list_deployments

Recent deployments of an app, or everything queued and in progress.

read

get_deployment

Status plus the last N build and deploy log lines (default 100).

read

get_application_logs

Last N container log lines of a running application.

read

Environment server config

Variable	Meaning
`COOLIFY_URL`	Required. Instance URL, e.g. `https://coolify.example.com`.
`COOLIFY_TOKEN`	Required. API token, sent as a Bearer token.
`COOLIFY_READ_ONLY`	`1` refuses every mutating tool.
`COOLIFY_ALLOW_REVEAL`	`1` allows `list_envs` with `reveal: true`.
`COOLIFY_TIMEOUT_MS`	Per-request timeout, default `30000`.

FAQ

Questions

Which token permissions should I pick?

read is the minimum. Add read:sensitive so env values can be masked and compared (without it, list_envs shows keys only, set_envs can't tell unchanged from updated, and get_deployment has no build logs). Add write for env changes and deploy for deploy / start / stop / restart.

Never root. For a look-only setup, use read + read:sensitive and turn on read-only mode.

Does my token or my secrets leave my machine?

The server runs locally over stdio and talks only to your COOLIFY_URL. No telemetry. The token is never logged and is redacted from errors.

Env values are fetched so they can be masked; the agent (and so your model provider) only sees plaintext if you set COOLIFY_ALLOW_REVEAL=1 and the agent explicitly asks with reveal: true.

What's the difference between application and service env vars?

Applications (git / Dockerfile / Nixpacks builds) have build-time and runtime flags and a separate preview copy of each key for PR deployments. is_preview picks which copy you edit.

Services (one-click and docker-compose) have neither preview nor build-time flags. Coolify trims values and stores an empty value as null. After changing a service's envs, use restart_service; for apps, restart_application for runtime vars or deploy for build-time vars.

I'm on an older Coolify beta. Will the build-time flag work?

Yes. Current Coolify calls it is_buildtime (with is_runtime); older v4 betas used is_build_time. set_envs sends both and Coolify ignores the one it doesn't know.

Why does the first launch take a while?

npx -y github:amintt2/coolify-mcp clones the repository and compiles it the first time, then reuses its cache. It needs git on your PATH. You can also clone it, run npm install, and point your client at node /path/to/coolify-mcp/dist/index.js.

My client says it can't find npx.

GUI apps like Claude Desktop don't always see the PATH from your shell (common with nvm). Replace "npx" with the absolute path printed by which npx.

Is this an official Coolify project?

No. It's an independent, MIT-licensed project that uses Coolify's public v4 REST API.