Coolify MCP Server
Manage Coolify from Claude, Cursor, or any MCP client: 46 tools for deploying, debugging, and operating your self-hosted PaaS in plain English. Destructive operations ask a human first; secrets stay masked.
📖 coolify-mcp.stumason.dev · Tool reference · Prompts and resources · Remote / HTTP mode · Fleet · Doctor · Safety and security · Changelog
Install
You need a running Coolify v4 instance and an API token (Coolify → Keys & Tokens → API tokens). Pick one of three ways to run the server.
Claude Desktop, one-click. Download coolify-mcp.mcpb and drag it into Settings → Extensions. You are prompted for your Coolify URL and token. No Node install, no JSON editing.
Locally, in any MCP client. Claude Code:
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
Codex CLI is the same with codex mcp add and --env. For Cursor, Claude Desktop or anything that takes a JSON config:
{
"mcpServers": {
"coolify": {
"command": "npx",
"args": ["-y", "@masonator/coolify-mcp"],
"env": {
"COOLIFY_BASE_URL": "https://your-coolify-instance.com",
"COOLIFY_ACCESS_TOKEN": "your-api-token"
}
}
}
}
Remotely, as a container inside your Coolify. Deploy the server next to the Coolify it manages and connect claude.ai, Claude Desktop or Claude Code to https://your-domain/mcp. Your Coolify token stays server-side; clients authenticate with OAuth 2.1. Five-minute setup in docs/http-mode.md.
Then run doctor
Whatever you configured, verify it in one command:
COOLIFY_BASE_URL="https://your-coolify-instance.com" COOLIFY_ACCESS_TOKEN="your-api-token" \
npx @masonator/coolify-mcp doctor
It checks the config for the classic traps (unexpanded ${VAR}, pasted whitespace, a doubled /api/v1), that Coolify is reachable and not hidden behind a Cloudflare Access login, that the token is accepted and can deploy, and that your Coolify version is in the tested range. Each failure comes with a one-line fix. Add --json for scripts. It never prints a secret. Every check is described in the doctor guide.
Behind a proxy or Cloudflare Access
Add --header "Key: Value" args (repeatable) for a generic auth proxy. For Cloudflare Access, set CF_ACCESS_CLIENT_ID and CF_ACCESS_CLIENT_SECRET (an Access service token) and every request to Coolify carries them, in both local and remote mode. Setup.
What it does
Every tool takes an action; run one with no arguments and it lists what it accepts. The tool reference has the full table. In short:
- Work out what is wrong.
diagnose_appanddiagnose_servertake a name, domain, IP or UUID;find_issuesscans the estate;logsreads any container. - Deploy and roll back.
deploywaits for a terminal status and returns the log tail on failure. Start, stop and restart anything withcontrol. - Create and destroy. Applications, databases (8 engines), services, projects and environments, with
environments verify_appto prove a binding before you mutate it. - Handle the configuration. Env vars, storages, scheduled tasks, backups, tags, private keys, GitHub apps, cloud tokens. Secrets come back masked unless you ask for one exact key.
- Move across the whole estate.
bulk_env_update,redeploy_project,stop_all_apps, each behind a human confirmation that states the blast radius. - Search the Coolify docs with
search_docs.
Lists return uuid/name/status summaries, 90–99% smaller than the raw API; get_* tools fetch one resource in full. The whole tool list costs about 8,900 tokens of context.
Workflows, not just tools
Three prompts ship as slash commands: troubleshoot_application, explain_failed_deploy and estate_health. Pick one and the model walks the workflow with the tools it already has. Two resources, coolify://overview and coolify://application/{uuid}, are reads your client can attach; both go through the same masking as every tool call, and neither offers a way to ask for plaintext. A prompt whose tools are not registered is not listed, so read-only mode never offers a dead end. Prompts and resources.
Several Coolify instances
Set COOLIFY_INSTANCES to a JSON array of { name, url, token } alongside your default config. Every tool then takes an optional instance, list_instances reports what is configured, and every destructive confirmation names the instance it targets. Single-instance installs are byte-identical. A fleet is one trust domain; agencies with a Coolify per client should run one server per client. Fleet guide.
Safe to point at production
Destructive operations stop and ask you, in your own client, before anything happens, on clients that support elicitation (Claude Code, VS Code Copilot). In remote mode the guard fails closed. Secrets are masked at the API boundary, log output is wrapped as untrusted data so a poisoned log line cannot issue instructions, and an eval suite red-teams both claims on every change. Details.
Works against Coolify v4.0 through v4.3. The v4.2 GET-to-POST change and the v4.2 secrets and Member-role restrictions are handled; see compatibility.
Coolify's own MCP server, and when you want this one
Coolify ships an MCP server of its own, built into the product. Enable it in Settings → Advanced (and per team), point your client at https://your-coolify/mcp, and there is nothing to install: it runs inside the instance, so no third-party code ever holds your token. If you run one Coolify, with one team, and you mostly want to ask it questions, use that. It is the shortest path and it costs you nothing.
At the time of writing Coolify documents its server as read-only, with write operations planned. It is moving quickly, so check the Coolify docs for where it has got to. There is also an official CLI if you would rather script than converse.
This server is for the jobs those two do not cover yet.
A rough rule. One instance and read-only questions, with no setup: use Coolify's. Scripting and CI: use the CLI. Several instances, writes you want a human gate in front of, a client that only speaks stdio, or you want to be told why it is broken: this one.
Other third-party Coolify MCP servers exist. Choose on transport, on how many instances you need to reach from one connection, and on what happens the moment before something is deleted.
Example prompts
Give me an overview of my infrastructure
Diagnose my shop.example.com app
Find any issues in my infrastructure
Deploy application {uuid} and wait for it to finish
Update the DATABASE_URL env var for application {uuid}
Restart all applications in project {uuid} on instance staging
How do I fix a 502 Bad Gateway error in Coolify?
Development
git clone https://github.com/StuMason/coolify-mcp.git
cd coolify-mcp && npm install
npm run build && npm test
COOLIFY_BASE_URL="https://your-coolify.com" COOLIFY_ACCESS_TOKEN="token" node dist/index.js
Tool descriptions are prompts, so evals/ measures whether a model picks the right tool and whether attacker-controlled output can make it misbehave; contract snapshots gate every PR. See evals/README.md. Contributions welcome: CONTRIBUTING.md and the architecture and API-gotcha notes in CLAUDE.md.
Work with me
I'm Stu Mason. I build MCP servers, AI integrations and agentic systems for agencies, SMEs and enterprise. This repo is what that work looks like in the open.
- An MCP server for your product. Give Claude, Cursor and every other AI client a proper way into your API, like this one.
- Answers from your own stuff. AI that answers from your documents and data, with the receipts, instead of guessing. Can stay on your own servers.
- Work that runs itself. Jobs on a schedule that sort, check and report, with a person signing off before anything goes out.
White-label under your own name if you're an agency. And if a job doesn't need AI, I'll say so before anyone's paid for anything.
📮 [email protected] · stumason.dev · coolify-mcp.stumason.dev
Privacy Policy
This server collects nothing about you. There is no telemetry, no analytics and no phone-home, and there is no hosted service behind it.
Your Coolify API token goes to the instance you configured and nowhere else. The
only other outbound requests are a one-off documentation index refresh from
coolify.io, which carries a cache validator and no credentials, and in HTTP
mode a credential-free fetch of the connecting client's own metadata document.
Tool results go to your own MCP client, whose privacy policy governs what
happens next. The audit log writes to your own stderr and never contains token
values.
Full detail, including where in the code each claim is implemented, is in PRIVACY.md.
Links
- Coolify: the open-source, self-hostable PaaS this server drives
- MCP Registry: listed as
io.github.StuMason/coolify - laravel-coolify: deploy Laravel to Coolify with a dashboard, Artisan commands, and generated Dockerfiles
- Model Context Protocol
MIT © Stu Mason. If this is useful, ⭐ the repo. If it saved you an evening, sponsor a coffee.
