Coolify MCP puts 46 tools behind a single action parameter
MCP server for Coolify — 42 optimized tools for managing self-hosted PaaS through AI assistants
At a glance
- What is it?
- StuMason/coolify-mcp is a TypeScript MCP server that exposes Coolify v4 through an action parameter per tool, three installation shapes including an OAuth 2.1 container mode, and destructive operations that stop for a human before they run.
- Who is it for?
- coolify-mcp earns its place when your Coolify instance needs more than read-only questions, and when you can accept a third-party process holding a token that can deploy and destroy. Verify three things before pointing it at production: that your Coolify version sits inside v4.0 to v4.3, that your client supports elicitation so destructive tools stop and ask, and that you have chosen between one server per client and a pooled fleet, since a fleet is one trust domain.
- Can I use it commercially?
- Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 3 days ago.
- What is it written in?
- Mainly TypeScript, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on November 15, 2026, and from our analysis. They are not legal advice.
Star history
- StuMason/coolify-mcp625 ★ · +35
| Repository | 2026-09-12 | 2026-11-15 |
|---|---|---|
| StuMason/coolify-mcp | 590 | 625 |
35 Stars in the last 64 days, measured from the daily GitHub snapshot. Compare with other projects
Editorial analysis
Every tool takes an action, and the list costs 8,900 tokens
Every tool in this server takes an action argument, and calling one with no arguments at all makes it list what it accepts. That choice comes with a stated cost and a stated payoff. The payoff is context: lists come back as uuid, name and status summaries, described as 90 to 99 percent smaller than the raw API, while the get_ tools fetch one resource in full when you need the fields the summary dropped. The cost is that the whole tool list is about 8,900 tokens of context.
The tool count is held in place by scripts rather than by a changelog line. package.json declares check:tool-count pointing at scripts/check-tool-count.mjs, with a check:tool-count:fix sibling, next to check:spec-drift for client specification drift and build:chunks with check:chunk-drift for the OpenAPI chunk split. The numbers are not perfectly aligned across the repository: the project description says 42 tools, while the README and the package.json description both say 46. package.json declares version 3.9.0, and releases v3.7.0, v3.8.0 and v3.9.0 all landed between September 30 and October 2, 2026.
Three install shapes, and the container keeps the token server side
Installation comes in three shapes, and what you are willing to install decides which one applies.
The shortest is a bundle: download coolify-mcp.mcpb from the latest release and drag it into Settings then Extensions in Claude Desktop, where you are prompted for your Coolify URL and token. No Node install, no JSON editing.
For any local MCP client the server is an npx package under the @masonator scope, registered in Claude Code like this:
claude mcp add coolify \
-e COOLIFY_BASE_URL="https://your-coolify-instance.com" \
-e COOLIFY_ACCESS_TOKEN="your-api-token" \
-- npx @masonator/coolify-mcp@latestCodex CLI takes the same shape with codex mcp add and --env, and clients that read a JSON config, Cursor and Claude Desktop among them, take this instead:
{
"mcpServers": {
"coolify": {
"command": "npx",
"args": ["-y", "@masonator/coolify-mcp"],
"env": {
"COOLIFY_BASE_URL": "https://your-coolify-instance.com",
"COOLIFY_ACCESS_TOKEN": "your-api-token"
}
}
}
}The third shape is remote. You deploy the server as a container inside the Coolify it manages and point clients at https://your-domain/mcp. The Coolify token then stays server side and clients authenticate with OAuth 2.1. The Dockerfile backs that mode with a /data volume holding registered clients and token hashes and never a Coolify credential, passes COOLIFY_BASE_URL and COOLIFY_ACCESS_TOKEN at runtime, runs node dist/index.js as its default command, and switches to dist/http.js with MCP_PUBLIC_URL set for HTTP mode.
Doctor looks for the mistakes other people paste in
Whichever route you took, the next instruction is one command:
COOLIFY_BASE_URL="https://your-coolify-instance.com" COOLIFY_ACCESS_TOKEN="your-api-token" \
npx @masonator/coolify-mcp doctorDoctor is a checker for the errors that show up in other people's configurations. It looks for unexpanded ${VAR} text, for whitespace pasted in along with a token, and for a doubled /api/v1 sitting in the base URL. It confirms that Coolify answers and that the instance is not hidden behind a Cloudflare Access login, that the token is accepted and can actually deploy, and that the version on the other end falls inside the tested range. Each failure arrives with a one-line fix, --json makes the output scriptable, and the command states that it never prints a secret.
Destructive tools stop and name the blast radius first
Destructive tools pause before they act. On clients that support elicitation, named as Claude Code and VS Code Copilot, the stop happens in your own client before anything changes, and the estate-wide commands state what they are about to do: bulk_env_update, redeploy_project and stop_all_apps each sit behind a human confirmation that spells out the blast radius. In remote mode the guard fails closed, so a client that cannot ask cannot proceed.
Two claims are red-teamed by an eval suite on every change, and they are the two that would matter most in production: secrets stay masked at the API boundary, and log output arrives wrapped as untrusted data. That second claim is the interesting one, because deploy waits for a terminal status and hands back the log tail on failure, which means container output flows straight into the model that asked for it.
Logs come back as untrusted data, secrets do not come back at all
Masking is not a display filter. A secret value comes back masked unless you ask for one exact key, and neither of the two resources offers any way to request plaintext. Those resources are coolify://overview and coolify://application/{uuid}, and both go through the same masking as every other tool call.
Log handling is the other half of the safety story. A container log is input that anyone with push access to your application can influence, so it is wrapped as untrusted data on the way back, which is what stops a poisoned log line from being read as an instruction. The read path is broad: the logs tool reads any container, diagnose_app and diagnose_server take a name, domain, IP or UUID, and find_issues scans the estate. Whichever tool you use for debugging, the volume of untrusted text entering the context window is the part to think about.
One server can hold several Coolify instances
A single server can hold several instances. Set COOLIFY_INSTANCES to a JSON array of objects with name, url and token alongside your existing single-instance config, and every tool gains an optional instance argument. list_instances reports what is configured, and every destructive confirmation names the instance it is about to touch, which is the detail that matters once two clients with different blast radii share a process. Single-instance installs are described as byte-identical to before, so the fleet option costs nothing if you never turn it on.
The fleet guide is blunt about its limit: a fleet is one trust domain. An agency that runs a Coolify per client is told to run one server per client rather than pooling them behind a single configuration.
Behind Cloudflare Access, the token is not the only credential
When Coolify does not answer on the public internet, the API token stops being the only credential in play. Behind a generic auth proxy, pass repeatable --header "Key: Value" arguments. Behind Cloudflare Access, set CF_ACCESS_CLIENT_ID and CF_ACCESS_CLIENT_SECRET to an Access service token, and every request to Coolify carries both of them, in local mode and in remote mode alike.
Doctor checks the same condition from the other direction. It flags an instance that is reachable but sitting behind an Access login, which is the failure that otherwise reads as a rejected token and sends people off to regenerate credentials that were never wrong. The same header mechanism covers a reverse proxy that terminates auth itself, which is the common case for a Coolify instance on a private network.
Coolify ships its own MCP server, and this one is the other option
Coolify ships an MCP server of its own, so the useful question is when to use which. The built-in one is enabled in Settings then Advanced, and per team, and clients point at https://your-coolify/mcp with nothing to install. It runs inside the instance, so no third-party code ever holds your token. For one Coolify with one team where you mostly want to ask questions, that is the shortest path and it costs nothing. At the time of writing, Coolify documents its server as read-only with write operations planned, and the project points you at the Coolify documentation for how far that has moved. There is also an official CLI in the Coolify labs organisation.
This server sits on the other side of that line. Its tools cover diagnosis, deploy and rollback, creating and destroying applications, databases across 8 engines, services, projects and environments, configuration such as env vars, storages, scheduled tasks, backups, tags, private keys, GitHub apps and cloud tokens, estate-wide operations, and a search_docs tool that queries the Coolify documentation itself. Three prompts ship as slash commands, troubleshoot_application, explain_failed_deploy and estate_health, and a prompt whose tools are not registered is not listed, so a read-only client is never offered a workflow it cannot finish. It is tested against Coolify v4.0 through v4.3, with the v4.2 GET-to-POST change and the v4.2 secrets and Member-role restrictions handled.
Editorial conclusion
coolify-mcp earns its place when your Coolify instance needs more than read-only questions, and when you can accept a third-party process holding a token that can deploy and destroy. Verify three things before pointing it at production: that your Coolify version sits inside v4.0 to v4.3, that your client supports elicitation so destructive tools stop and ask, and that you have chosen between one server per client and a pooled fleet, since a fleet is one trust domain. If Coolify's own server answers everything you need, use that instead.
Frequently asked questions
Why would I need an MCP server?
To manage Coolify from Claude, Cursor, or any MCP client: 46 tools for deploying, debugging, and operating your self-hosted PaaS in plain English. You need a running Coolify v4 instance and an API token from Coolify then Keys & Tokens then API tokens.
What does MCP do exactly?
In this project the server exposes 46 tools against a Coolify v4 instance, three prompts as slash commands, and two resources, coolify://overview and coolify://application/{uuid}, that a client can attach as reads.
Does the Coolify MCP server need Node installed on my machine?
Not for the one-click route. Download coolify-mcp.mcpb and drag it into Settings then Extensions in Claude Desktop, where you are prompted for your Coolify URL and token. The local route needs npx, and the remote route needs neither.
Which Coolify versions does this MCP server support?
Coolify v4.0 through v4.3. The v4.2 GET-to-POST change and the v4.2 secrets and Member-role restrictions are handled, and the doctor command fails when the version on the other end is outside the tested range.
Can one Coolify MCP server manage several Coolify instances?
Set COOLIFY_INSTANCES to a JSON array of name, url and token objects alongside your default config, and every tool takes an optional instance argument while every destructive confirmation names its target. A fleet is one trust domain, so agencies with a Coolify per client are told to run one server per client.
Should I use this server or the MCP server built into Coolify?
Coolify's own server is enabled in Settings then Advanced, runs inside the instance so no third-party code holds your token, and is documented as read-only with write operations planned. This one covers Coolify v4.0 through v4.3 and puts destructive operations behind a human confirmation.
Official sources
Add this badge to your README
If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.
[](https://hysenlabs.com/projects/stumason-coolify-mcp)Star history chart for your README
[](https://hysenlabs.com/projects/stumason-coolify-mcp)Was this useful?