coolify-mcp: Driving a Self-Hosted Coolify PaaS From an MCP Client

The gap between a Coolify dashboard and an assistant that can act

Coolify gives you a web UI and an HTTP API. Neither is convenient when the question is conversational: why did this app fail to deploy, which containers are unhealthy across the estate, what does the last hundred lines of that log say. The README frames the project as managing Coolify from Claude, Cursor or any MCP client, with destructive operations asking a human first and secrets staying masked. That framing is the actual product. The tools exist so a model can resolve a name, domain, IP or UUID into a resource, read its state, and then change it under a confirmation step. The audience is someone already running Coolify v4 who wants an assistant in the loop for operations work, not someone shopping for a PaaS.

One action parameter per tool, and summaries instead of raw API payloads

The mechanism is uniform. Every tool takes an action, and running a tool with no arguments lists what that action accepts, which means the schema is discoverable from inside the client rather than only from the docs. Read paths are split deliberately: list operations return uuid, name and status summaries, while get_* tools fetch one resource in full. The README claims those summaries are 90 to 99 percent smaller than the raw API response, and states the whole tool list costs about 6,600 tokens of context. That second number is the one that matters for adoption, because tool definitions sit in the context window on every turn. Two resources, coolify://overview and coolify://application/{uuid}, are attachable reads that pass through the same masking as tool calls, and the README says neither offers a way to ask for plaintext. Three prompts ship as slash commands: troubleshoot_application, explain_failed_deploy and estate_health.

Three install paths, two environment variables and a doctor subcommand

The prerequisites are a running Coolify v4 instance and an API token from Keys and Tokens. For Claude Code the README gives a single command: claude mcp add coolify with -e COOLIFY_BASE_URL and -e COOLIFY_ACCESS_TOKEN, then npx @masonator/coolify-mcp@latest. Codex CLI uses the same shape with codex mcp add and --env. Clients that take JSON get an mcpServers block with command npx, args ["-y", "@masonator/coolify-mcp"] and the same two environment variables. Claude Desktop has a one-click route: download coolify-mcp.mcpb and drag it into Settings, Extensions, with no Node install. Remote mode deploys the server as a container next to the Coolify it manages, and clients authenticate with OAuth 2.1 so the Coolify token stays server-side. The verification step is worth doing before anything else: run npx @masonator/coolify-mcp doctor with the same two variables set. The README says it catches unexpanded ${VAR}, pasted whitespace and a doubled /api/v1, checks reachability, checks that Cloudflare Access is not blocking the call, checks the token can deploy, and checks the Coolify version against the tested range, with a one-line fix per failure and a --json mode for scripts. It never prints a secret.

Masking at the API boundary and a confirmation gate that fails closed

Secrets come back masked unless you ask for one exact key, and the README places that masking at the API boundary rather than in the model prompt, which is the right layer. Log output is wrapped as untrusted data so a poisoned log line cannot issue instructions, and the README says an eval suite red-teams both claims on every change. Destructive operations stop and ask in your own client before anything happens, but only on clients that support elicitation, which the README names as Claude Code and VS Code Copilot. In remote mode the guard fails closed. That distinction deserves attention: on a client without elicitation support, the confirmation step is not a universal guarantee, and the README's own phrasing scopes it to clients that support the feature. Bulk operations such as bulk_env_update, redeploy_project and stop_all_apps sit behind a human confirmation that states the blast radius, which is the only sensible design for actions that touch every app at once.

Fleet mode is one trust domain, and that is a real boundary

Set COOLIFY_INSTANCES to a JSON array of objects with name, url and token, and every tool gains an optional instance parameter, list_instances reports the configuration, and destructive confirmations name the target instance. Single-instance installs stay byte-identical, so this costs nothing if you do not need it. The limitation is stated plainly in the README: a fleet is one trust domain, and agencies running a Coolify per client should run one server per client instead. That is not a missing feature, it is a scoping decision, and it means the multi-instance mode suits an organisation that owns all the instances rather than a consultancy that does not. If your business model is one Coolify per customer, fleet mode is the wrong tool and the README says so before you find out the hard way.

Coolify's built-in MCP server versus this one

Coolify ships its own MCP server inside the product. Enable it in Settings, Advanced, and per team, point your client at https://your-coolify/mcp, and there is nothing to install because it runs inside the instance. The README's comparison section is where the supplied material runs out, so treat the following as the honest state of things: the in-product server wins on installation and on having no third party in the request path, while coolify-mcp adds the pieces described above, namely the doctor preflight, the masked read resources, the three workflow prompts, the bulk tools with stated blast radius and the fleet configuration. If you only need a handful of reads against a single instance and you are comfortable enabling the built-in server, the install-free option is the shorter path. Choose coolify-mcp when you want the diagnostics and safety scaffolding around the calls, and be aware that you are then depending on a separate package tracking Coolify's API changes.

Version drift, client support and the cost of tracking Coolify

The README states support for Coolify v4.0 through v4.3 and says the v4.2 GET-to-POST change plus the v4.2 secrets and Member-role restrictions are handled, with a compatibility section in the tool reference. That is a bounded range. Coolify's API has already changed shape once inside it, which tells you the maintenance burden is real: a PaaS that moves from GET to POST for a class of operations forces a wrapper to follow, and the doctor command exists partly because misconfiguration is common enough to warrant its own subcommand. Three releases landed in the three days before the last push, v3.0.0 through v3.2.0, so the project is moving quickly and you should expect to pin a version rather than float on @latest if you care about reproducibility. On licensing, the repository is MIT, which permits commercial use and modification; that is a description of the licence identifier, not legal advice, and if you redistribute the package inside a product you should read the licence text yourself. The other cost is context: about 6,600 tokens for the tool list is a standing tax on every conversation, and it is the number to weigh against running a narrower set of tools.

Editorial conclusion

Adopt it if you already run Coolify v4 and want an assistant to read logs, diagnose apps and run deploys without hand-copying UUIDs into curl calls, and start by running the doctor subcommand against your instance before wiring it into a client. Skip it if you manage a Coolify per client under one shared token, since the fleet guide treats a fleet as a single trust domain, or if your client does not support elicitation and you cannot run remote mode, where the guard fails closed instead. Verify two things first: that your Coolify version sits inside the tested v4.0 to v4.3 range, and that your client actually surfaces the destructive-operation prompt rather than silently proceeding.

Official sources

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