An MCP server we wrote so the AI clients we already use can read and operate the projects on our Coolify instances. Built for our own work, used every day, opened up under MIT.
We run four separate Coolify instances with dozens of applications, databases and services across them. Finding out which box something lived on meant opening four dashboards in turn and typing the same word into four search boxes. Then a fifth tab for the log.
Coolify’s REST API was already there. What was missing was a way for the model already open in the editor to speak it. coolify-mcp does that: one MCP server showing every Coolify instance and every Coolify team you have from a single connection. Free, MIT licensed, source public. We are not affiliated with the Coolify project — we run Coolify, and we wrote a client for ourselves. It is a small utility, not a product line, and the honest recommendation for a one-instance setup is further down this page.
One search hits every connection at once, and each row is tagged with the instance it came from: uuid, name, type, status, fqdn, project, environment, server, last update. Coolify returns roughly eighty fields per resource; nine come back.
The deployment history is listed, the latest one opened, the build output read. No SSH session, no hunting for a tab.
The container log lands in the client. You read the error with the model and decide what to do in the same conversation.
Environment variables sit in their own tool and need a separate Coolify ability. When a resource config is read, credential-shaped values are masked unconditionally — there is no reveal switch.
The deploy is triggered and, if you ask, followed until it settles. Start, stop and restart live in the same place.
Not a design preference — a direct consequence of how Coolify scopes a token.
That is the whole model. A Coolify token is bound in the database to the team that was active when it was created, and the REST API has no team-switch parameter — no X-Team-Id header, no ?team= query. Another team’s UUIDs come back 404.
So a second team is a second connection, pointing at the same base URL. That is why there is no separate “team” concept inside the server: N connections cover N instances and M teams the same way.
With more than one connection every tool grows an instance parameter. Reads may fall back to a designated connection; writes and deletes require an explicit name, with no default. Guessing wrong on a read costs one wasted call; guessing wrong on a deploy costs an incident.
The search tool alone accepts a wildcard: it queries every connection in parallel and tags each row with its origin. If one box is unreachable the table still comes back, the failure listed beside the rows that answered.
15 tools are registered by default; 11 when the server is read-only, 16 when destructive operations are enabled. Everything else in Coolify’s API is reached through a three-step door: search the operation, read its schema, run it. Handing a model hundreds of tool definitions burns context on schemas it never calls.
It is built at release time from the Coolify 4.2.0 specification and covers 189 operations: 74 read, 86 write, 29 destructive, three flagged as provisioning billable cloud infrastructure. An instance newer than the catalog may expose operations we do not list, and a search matching nothing says so and names the spec version.
Coolify’s OpenAPI document is generated from PHP attributes and is wrong in places. Validating hard against it would reject valid calls with no override. So the body passes through unchanged and Coolify’s own field errors come back verbatim. Path parameters are validated strictly — those come from the URL template.
The tools kept in the open cover exactly these six steps.
Coolify uuids are opaque and appear nowhere until something lists them. One request returns applications, databases and services.
Build settings, domains, ports, health checks, git source, the server it sits on.
The container log — the most common reason to open the dashboard at all.
A separate tool behind a separate ability. Most deploys that break on a wrong value are diagnosed here.
Trigger it. Ask it to wait and it polls until the deployment settles.
The deployment record is read back, build output included. The loop closes.
A Coolify token can operate your infrastructure. Most of the server’s design comes from sitting with that sentence.
It detects the MCP clients on the machine, prints a unified diff of every file it would touch, and writes only after you approve. It merges without disturbing other MCP servers, preserves JSONC comments, refuses to write into a config it cannot parse.
What lands in your client config is the command to run and, at most, a connection name. The base URL and token are never written to a file — those files get synced, backed up and screen-shared.
CLI clients inherit your shell. Editors inherit the environment of whatever launched them, which on macOS is often not your shell. Claude Desktop inherits nothing and needs a registry file with a token command or keychain entry. doctor tells you which case is yours.
check answers two questions: is the instance reachable, does the token work. doctor reports config health and scans for credentials at rest — Sanctum-shaped tokens, literal Bearer headers, credential-shaped env values, readable file modes. Exit code 2 means one is on disk. Findings never contain a secret value.
The destructive tool is not registered unless its flag is set — it does not appear and refuse, it is simply absent. With the flag off no tool carries a destructive hint, so a host auto-approving non-destructive tools is approving something genuinely non-destructive. The gate is enforced at registration, at dispatch, and in the HTTP client.
Set per connection or process-wide, it refuses every non-GET before it leaves, whatever the token is scoped to. When every connection is read-only, the write and destructive tools are never registered. No lower setting widens it.
The default install is stdio: your client starts the server, a copy runs on every machine you work from, and the Coolify token sits on all of them.
In HTTP mode the server runs once and serves every client you own. The Coolify token stays on the server and clients present a bearer token that has nothing to do with Coolify, so a leaked client credential is not a leaked Coolify credential. That client token is mandatory, at least 32 characters, and the server refuses to start without it. It binds to localhost unless you say otherwise and does not terminate TLS — put a reverse proxy in front, which on Coolify is Traefik and already there.
You can run it as a container on the Coolify instance it manages. That is one less machine to patch, with a cost we are not hiding: if that instance goes down, the MCP server goes down with it — precisely when you would want it. Usually worth paying. Choose it deliberately.
Coolify’s web terminal is a websocket, not REST. If you need to run something inside a container this will not help, and we did not ship a tool that pretends otherwise.
No notification API. No S3 storage CRUD. No healthcheck endpoint — healthchecks are fifteen-odd fields on the application update call. No shared environment variables. No team writes.
Coolify does not paginate, so the full array is fetched and filtered in-process. A resource created or deleted between pages will shift the rows. This is not a snapshot.
Five tokens on one Coolify account share one allowance, so fanning a search out across connections owned by the same user draws on the same bucket.
Roughly twenty-two fields are stripped server-side on a PATCH. A no-op rather than an error, and nothing we can do beyond saying so.
The queue response shape has not been confirmed against a live instance. With no deployment id, the handler falls back to the application’s deployment history — timestamp-based, and wrong under concurrent deploys.
If you run one Coolify with one team, you may not need this at all.
Nothing to install, nothing to configure, and it lives where the data is. All ten of its tools are read-only and scoped to the token’s team. Run one Coolify with one team and you will probably be happy with it — we would say so ourselves.
The established third-party server: around forty-two curated, hand-shaped tools, popular for the right reasons. Its model is one instance per process, so three Coolify instances means three servers — and a single call still cannot search across them.
If you run the same four steps every time, having a model do them is slower and costlier than writing them down once. Repeatable work belongs in CI. This is for questions whose answer you do not already know.
The only axis where we differ. Four boxes and no memory of which one an app lives on becomes one question.
Several teams on one instance means several named connections, all visible from one place.
Logs, environment variables and deploy status arrive in the window you are already in.
When a deploy breaks at night, reading the log does not start with finding the right dashboard.
doctor emits a machine-readable report with stable finding codes you can match in a pipeline.
MIT licensed, source open. Fork it, cut what you do not need. You do not have to ask us.
No. MIT licensed and free. There is no installation package or support plan attached to it; the source and the license are on GitHub.
No. We run Coolify and wrote a client for ourselves — that is the whole relationship. No partnership with Coollabs or the Coolify project, and nothing here is endorsed by them.
Into no configuration file at all. The installer writes a pointer; the token reaches the server from an environment variable, a secret-manager command, or the OS keychain. The registry file schema has no token property, so putting one there is a validation error rather than a discouraged option.
The installer knows eight client adapters: Claude Code, Cursor, Codex CLI, Kimi CLI, Zed, OpenCode, Claude Desktop and MiniMax. MiniMax is marked unverified and only prints — a wrong top-level key in that file would corrupt your model configuration.
With stdio your client starts the server and the Coolify token sits on every machine you use. Over HTTP the server runs in one place and clients present an unrelated bearer token. On a single machine, stdio is enough.
Node.js 20.10 or newer, with no native dependencies. In HTTP mode a client auth token of at least 32 characters is required and the server refuses to start without it.
Related
The same idea one layer down: an MCP server for our Hetzner accounts.
The tools we wrote for ourselves and then opened up.
The hosting these tools run on: setup, monitoring, maintenance.
Server design, container infrastructure and deployment pipelines.
Questions about the tool are faster on GitHub. For work, write to us here.
Book a free 30-minute discovery call with our team.
Our network and cyber security work is carried out by a team holding internationally recognised Cisco certification.
Issued by Cisco · Holder: Devrim Tunçer
A certification covering security operations centre (SOC) competency: security monitoring, incident response and analysis of network attacks. It is the foundation we rely on for intrusion detection, log correlation and post-incident response work.
Cisco training certificate · completed January 2023
Covers networking fundamentals: routing, switching, IP addressing and network security. The knowledge base we draw on for enterprise network setup and segmentation.