coolify-mcp: 45 MCP tools for running a self-hosted Coolify from Claude or Cursor

What coolify-mcp is for, and who it is not for

Coolify is a self-hosted PaaS: you run it, it runs your containers. Its API is broad, and broad APIs are awkward to use from a chat window. coolify-mcp sits between the two. It is a Model Context Protocol server written in TypeScript that exposes Coolify operations as tools an AI assistant can call, so a request like "why did the last deploy of the api app fail" becomes a sequence of API calls the model makes on your behalf.

The intended user is someone who already has a Coolify v4 instance and an API token, and who works inside an MCP client such as Claude Code, Claude Desktop, Cursor, Codex CLI or claude.ai. If you have never run Coolify, this project adds a layer of indirection over something you do not yet have. The README is explicit that you need a running Coolify v4 instance and a token from Coolify's Keys & Tokens screen before any of the install paths make sense.

The scope is deliberately narrower than "the Coolify API in a chat box". The README describes list responses as uuid/name/status summaries, 90 to 99 percent smaller than the raw API, with separate get_* tools for fetching one resource in full. That is a context-budget decision, not a completeness decision, and it shapes what the model can see at any moment.

How the tool layer is organised

Every tool takes an action parameter. Calling a tool with no arguments makes it list what it accepts, which is the project's substitute for reading a schema by hand. The README groups the tools by job rather than by API endpoint: diagnose_app and diagnose_server take a name, domain, IP or UUID; find_issues scans the whole estate; logs reads any container. Deploy and rollback sit under deploy, which the README says waits for a terminal status and returns the log tail when the deploy fails. Start, stop and restart are folded into a single control tool.

Creation and destruction cover applications, databases across 8 engines, services, projects and environments, with environments verify_app offered as a way to prove a binding before you mutate it. Configuration tools handle env vars, storages, scheduled tasks, backups, tags, private keys, GitHub apps and cloud tokens. Secrets come back masked unless you ask for one exact key. Estate-wide operations include bulk_env_update, redeploy_project and stop_all_apps, each behind a human confirmation that states the blast radius.

The README states the whole tool list costs about 6,600 tokens of context. That number matters more than it looks: it is the fixed tax every conversation pays before the model does anything. The summarised list responses are the other half of the same budget argument.

Installing coolify-mcp and running a first diagnosis

There are three documented paths. The one-click route is a Claude Desktop extension: download coolify-mcp.mcpb from the latest release and drag it into Settings, Extensions. You are prompted for your Coolify URL and token, with no Node install and no JSON editing.

For any other MCP client, the local route uses npx. This is the Claude Code form from the README, and it registers the server with your Coolify base URL and access token as environment variables.

claude mcp add coolify \
  -e COOLIFY_BASE_URL="https://your-coolify-instance.com" \
  -e COOLIFY_ACCESS_TOKEN="your-api-token" \
  -- npx @masonator/coolify-mcp@latest

The README notes Codex CLI takes the same shape with codex mcp add and --env. Clients that read a JSON config instead use this block, with the same two environment variables.

{
  "mcpServers": {
    "coolify": {
      "command": "npx",
      "args": ["-y", "@masonator/coolify-mcp"],
      "env": {
        "COOLIFY_BASE_URL": "https://your-coolify-instance.com",
        "COOLIFY_ACCESS_TOKEN": "your-api-token"
      }
    }
  }
}

Whichever path you pick, the README says to verify it with doctor before trusting it. The command takes the same two variables and prints a pass or fail per check, never a secret.

COOLIFY_BASE_URL="https://your-coolify-instance.com" COOLIFY_ACCESS_TOKEN="your-api-token" \
  npx @masonator/coolify-mcp doctor

According to the README, doctor looks for the classic traps: an unexpanded ${VAR}, whitespace pasted along with the token, a doubled /api/v1 in the URL. It then checks that Coolify is reachable and not sitting behind a Cloudflare Access login, that the token is accepted and can deploy, and that your Coolify version falls in the tested range. Each failure comes with a one-line fix, and --json makes the output scriptable. A first real use after that is asking your client to run diagnose_app against an application name or UUID and reading what it returns.

The remote mode, and what it changes about the trust boundary

The third install path deploys the server as a container inside your own Coolify, next to the instance it manages, and exposes it at https://your-domain/mcp. Clients then authenticate with OAuth 2.1 and your Coolify token stays server-side. The Dockerfile shows the shape of this: a two-stage build on node:20-alpine, production dependencies installed with npm ci --omit=dev, a /data volume owned by the node user, and an entrypoint of node with CMD dist/index.js. The comments in the Dockerfile state that the default is still the stdio server, and that HTTP mode is enabled by overriding the command with dist/http.js and setting MCP_PUBLIC_URL. The same comments say the /data volume holds OAuth artefacts only, registered clients and token hashes, never a Coolify credential.

That separation is the interesting part. In local mode your Coolify token lives in your client's config on your machine. In remote mode it lives in the container and clients never see it. The README also states that in remote mode the destructive-operation guard fails closed, whereas in local mode it depends on the client supporting elicitation. Those are two different failure postures, and the README is clear that only Claude Code and VS Code Copilot are named as supporting elicitation.

Where coolify-mcp gets in the way

The confirmation guard is the project's main safety claim and also its main friction. On a client that does not support elicitation, the README does not describe a fallback for local mode; the guard is a feature of the client, not of the server. If you are driving this from a client outside the named ones, treat the destructive tools as unguarded in practice and check the security documentation before you point it at production.

The summarised list responses are a second trade-off. A 90 to 99 percent reduction in payload is what makes the tool list affordable in context, but it means the model sees uuid, name and status rather than the full resource. Anything that needs detail requires a follow-up get_* call, so a question that spans many resources turns into more round trips than a direct API script would take.

Fleet configuration is the third. COOLIFY_INSTANCES takes a JSON array of { name, url, token } entries, every tool gains an optional instance parameter, and destructive confirmations name the instance they target. The README then states the boundary plainly: a fleet is one trust domain, and agencies with a Coolify per client should run one server per client. If your reason for wanting fleet mode is multi-tenant hosting, the documented answer is no.

Finally, version support is a range, not a promise. The README says the server works against Coolify v4.0 through v4.3 and that the v4.2 GET-to-POST change and the v4.2 secrets and Member-role restrictions are handled. A Coolify v5 is not covered by that statement.

Coolify's built-in MCP server versus this one

Coolify ships an MCP server of its own, built into the product. The README describes enabling it under Settings, Advanced, and per team, pointing your client at https://your-coolify/mcp. Nothing is installed, because it runs inside the instance.

The difference is where the code runs and what it can do. The built-in server is inside Coolify, so there is no third-party process holding your token and no separate deployment to keep alive. coolify-mcp runs outside the instance, which is what lets it add things the product server does not have: the doctor preflight, the 45-tool surface with summarised list responses, the three shipped prompts (troubleshoot_application, explain_failed_deploy, estate_health), the coolify://overview and coolify://application/{uuid} resources, fleet configuration, and the documented eval suite that red-teams the masking and log-wrapping claims on every change. The README's own framing is that the built-in server means there is nothing to install, which is also its ceiling. If you want the smallest possible footprint and only need what Coolify exposes natively, the built-in server is the shorter path. If you want the doctor check and the workflow prompts, you are choosing this project.

Maintenance, licence and what upgrades cost you

The repository is not archived, and the last push was on 2026-09-10. Releases v3.0.0, v3.1.0 and v3.2.0 all landed within three days of each other in early September 2026, while package.json declares version 3.5.0, so the published version runs ahead of the release list shown here. The changelog is the place to read before upgrading, and the README links it.

The project is MIT licensed, which permits commercial use and modification; the LICENSE file is at the repository root. That is a statement about the licence text, not legal advice about your situation.

Upgrade cost is mostly version-drift work on the Coolify side rather than the npm side. The package pins nothing about your Coolify instance, so a Coolify upgrade can move the ground under the server. The repository carries scripts that suggest the maintainers watch for this: check:spec-drift, check:chunk-drift and check:tool-count all exist as npm scripts, and the README's compatibility note names the v4.2 API changes as handled. If you pin a Coolify version, pin the server too and read the changelog between the two. The doctor command checks that your Coolify version is in the tested range, which makes it the cheapest first step after any upgrade on either side.

Editorial conclusion

Adopt coolify-mcp if you already run Coolify v4 and want an MCP client to read logs, diagnose failures and trigger deploys without hand-writing curl calls against the API. Do not adopt it as a way to avoid learning Coolify, and do not point a multi-client agency setup at one server with several clients' tokens in COOLIFY_INSTANCES, because the fleet guide treats a fleet as one trust domain. Before wiring it into anything you care about, run the doctor command against your instance, confirm your Coolify version sits in the documented v4.0 to v4.3 range, and check whether your client supports elicitation, since that is what makes the destructive-operation confirmation appear.

Frequently asked questions

Official sources

1. License: MIT
2. Project website
3. README
4. Releases
5. StuMason/coolify-mcp on GitHub