Coolify MCP: Deploy & Manage Apps from Claude (2026)

TL;DR + what you actually need

• One secret: COOLIFY_ACCESS_TOKEN — an API token generated in your Coolify instance under Security → API Tokens. Pick permissions when you create it; start with read, add write and deploy only if you want the agent to change things.
• One URL: COOLIFY_BASE_URL — the address of your Coolify instance (e.g. https://coolify.example.com). It defaults to http://localhost:3000, which is wrong for almost everyone — set it.
• One package: @masonator/coolify-mcp — the stumason implementation, MIT-licensed, 42 consolidated tools covering deploys, app/database/service control, env vars, batch operations, and Coolify docs search. Runs via npx, Node 18+.

The copy-paste, if that’s all you came for:

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

Also worth knowing before you scroll: Coolify itself merged a built-in, read-only MCP server in May 2026. If all you want is “let Claude see my infrastructure,” you may not need to install anything at all — details in the first-party section below.

What Coolify is (for searchers who found Coolify first)

Coolify is an open-source, self-hostable platform-as-a-service — the project describes itself as an alternative to Heroku, Netlify, and Vercel. You install it on a VPS or your own hardware, point it at a Git repository, and it builds and runs your application in Docker containers with automatic HTTPS, a reverse proxy, and one-click databases (PostgreSQL, MySQL, MongoDB, Redis, and more). It was created by Andras Bacsai and is developed in the open at github.com/coollabsio/coolify, one of the most-starred self-hosting projects on GitHub.

The pitch is control without the platform tax: your servers, your data, no per-seat pricing, no vendor limits — a long catalog of one-click services (Plausible, n8n, Ghost, Supabase, and many others) deployable from a dashboard. The trade is that you’re now the platform team. Everything Coolify does runs through its REST API at /api/v1 — and that API is what the MCP server wraps. Many people run Coolify on a cheap VPS from Hetzner, DigitalOcean, or Hostinger; if you’re managing the VPS layer from an agent too, the Hostinger API MCP covers the machine while Coolify MCP covers what runs on it.

What the MCP server adds

The Coolify MCP server is a stdio process — a local subprocess your MCP client launches — that exposes Coolify’s REST API as tools the model can call. You say “the blog is down, restart it”; the agent calls diagnose_app with the domain, reads the health status, calls control with a restart action, then pulls application_logs to confirm recovery. Every step is a real API call against your instance, not a guess.

The implementation this guide uses — github.com/stumason/coolify-mcp by Stuart Mason (MIT) — is notable for two design decisions beyond raw API coverage. First, response trimming: the raw Coolify API returns enormous JSON payloads, and early MCP wrappers dumped them straight into the model’s context (one early bug report measured a single deployment response at 13,000+ tokens). The current server consolidates 42 tools that return summaries by default — the README claims roughly 85% fewer tokens than a naive implementation — with get_* calls for full detail when you need it. Second, smart lookup: tools accept human identifiers — an app name, a domain, a server IP — not just UUIDs, which is how people actually talk to a chat agent.

It also ships things no other implementation has: a full-text search_docs tool over an indexed copy of Coolify’s documentation (so the agent can answer “how do I configure a wildcard domain” without leaving the conversation), batch operations (restart_project_apps, bulk_env_update, an emergency stop_all_apps), and Hetzner / DigitalOcean provisioning tools that can create the server Coolify will deploy onto. Two smaller MIT alternatives exist — wrediam/coolify-mcp-server and felixallistar/coolify-mcp — but the stumason server is the most installed and the one our /servers/coolify catalog entry tracks.

One scope note: Coolify MCP operates at the platform layer — applications, services, deployments. For container-level work on machines Coolify doesn’t manage (inspect an arbitrary container, prune images, debug a compose stack), pair it with the Docker MCP server. They complement rather than overlap.

Coolify’s built-in /mcp endpoint (read-only)

In May 2026, Coolify creator Andras Bacsai merged PR #9862, which adds an instance-level MCP server to Coolify itself. Once a root-token user enables it (a toggle under Settings → Advanced, or POST /api/v1/mcp/enable), the instance serves an MCP endpoint at /mcp with 10 read-only tools: get_infrastructure_overview plus list/get pairs for servers, projects, applications, databases, and services. Auth uses the same API tokens as the REST API, results are scoped to the token’s team, and sensitive keys are scrubbed from responses.

How to choose between the two:

• Built-in /mcp: zero install, remote endpoint, read-only by design. Right answer for “give the agent visibility” — status checks, inventory questions, what-is-deployed-where. It cannot deploy, restart, or edit anything.
• Community server (stumason): local stdio install, full read-write surface — deploys, restarts, env vars, batch ops, provisioning, docs search. Right answer the moment you want the agent to act.

Our take: run the built-in endpoint for everyone on the team, and hand the community server with a scoped write token only to the people who actually deploy. If your Coolify version predates the feature, the toggle won’t exist — update the instance.

Auth: the Coolify API token

Coolify’s auth model is one bearer token, with permissions chosen at creation time. In your Coolify dashboard: Security → API Tokens → name the token → pick an expiration (7, 30, 60, 90 days, 1 year, or none) → select permissions → Create. The token looks like 67|abc123… and is displayed exactly once — copy it immediately. The MCP server sends it as Authorization: Bearer <token> on every request to /api/v1.

The permission options, per Coolify’s docs:

The third column is our practical mapping, not an official matrix — Coolify enforces permissions at the API endpoint level, so a tool fails with a permission error if the token can’t reach the endpoint it wraps. The decision that matters: scope the token to the workflow. A triage agent gets read (+ read:sensitive if it must read logs). A deploy agent gets read + write + deploy. Nothing gets root — Coolify’s own docs describe it as bypassing all permission checks, which is exactly the property you don’t want attached to a token sitting in an agent’s environment.

Why the caution is not theoretical: in January 2026 the Coolify team disclosed a batch of critical vulnerabilities (covered by The Hacker News) affecting older versions, with tens of thousands of instances exposed to the public internet. Patch your instance, don’t leave the dashboard world-reachable if you can avoid it, and treat the MCP token like the production credential it is — expiring, scoped, and out of source control.

Install (every client)

The community server is stdio-only — your MCP client launches npx -y @masonator/coolify-mcp as a subprocess with the two env vars set. The install panel below pulls its config from the canonical /servers/coolify catalog entry, so it stays in sync with the package name and env-var shape. Pick your client, copy, paste, fill in the token and URL, restart.

One-line install · Coolify

Open server page

Install

Cursor

One-click install

1-Click

VS Code

One-click install

1-Click

Claude Desktop

Copy configuration

Claude Code

Copy CLI command

CLI

Gemini

Copy CLI command

CLI

Codex

Copy CLI command

CLI

Windsurf

Copy configuration

ChatGPT

Add via Settings → Connectors

M

Manual

Copy configuration

Client-specific notes:

• Claude Code — one line: claude mcp add coolify -e COOLIFY_BASE_URL=https://your-instance.com -e COOLIFY_ACCESS_TOKEN=your-token -- npx @masonator/coolify-mcp@latest. Add --scope project to register it in the repo’s .mcp.json instead of your user config — but then keep the token out of the committed file. Full flag reference at /clients/claude-code.
• Claude Desktop — paste the JSON block from the install card into claude_desktop_config.json (on macOS: ~/Library/Application Support/Claude/), restart the app.
• Cursor — same JSON shape in ~/.cursor/mcp.json. See /clients/cursor.
• VS Code / Windsurf — the JSON snippet from the install card goes in the client’s MCP config file (~/.codeium/windsurf/mcp_config.json for Windsurf).
• Behind Cloudflare Access or an auth proxy? The server accepts --header flags appended to the args array so requests carry your proxy’s service token. Reserved headers (Authorization, Content-Type) are filtered so the Coolify bearer token can’t be clobbered.

Codex CLI

Codex reads MCP servers from ~/.codex/config.toml:

[mcp_servers.coolify]
command = "npx"
args = ["-y", "@masonator/coolify-mcp"]

[mcp_servers.coolify.env]
COOLIFY_BASE_URL = "https://your-coolify-instance.com"
COOLIFY_ACCESS_TOKEN = "your-api-token"

Restart Codex and confirm with codex mcp list. Prefer not to keep the token in TOML? Omit the env table and export both variables in the shell that launches Codex. Browse every supported client and its config path at mcp.directory/clients.

Tools walkthrough

The stumason server ships 42 tools, consolidated so related operations share one tool with an action parameter (e.g. projects handles list, get, create, update, delete). Grouped by what agents actually do with them:

Infrastructure & diagnostics

get_infrastructure_overview returns the whole-instance picture — servers, projects, app states — and is the natural first call in any session. diagnose_app and diagnose_server accept a domain name or IP (smart lookup) and return health plus suggested next actions; find_issues sweeps the instance for anything unhealthy. These three are the triage workhorses.

Servers, projects, environments

list_servers / get_server / validate_server cover the machines Coolify manages — validation checks SSH connectivity, the usual first suspect when deploys stall. projects and environments handle the organizational tree your apps live in.

Applications

The core group: list_applications, get_application, application_logs, an application CRUD tool, env_vars, and control (start / stop / restart). List responses are summaries by design — ask for the app by name with get_application when you need full config.

Databases & services

Same shape for the other two resource types: database covers the eight database engines Coolify can provision, database_backups reads backup state, and service manages one-click services. Each gets its own control and env_vars access.

Deployments

deploy triggers a deployment; list_deployments and deployment (get / cancel / list-for-app) watch and manage it. This is the group that turns “ship it” into a tool call — and the one your token’s deploy permission gates.

Batch operations

restart_project_apps, bulk_env_update, redeploy_project, and stop_all_apps — the emergency lever. Useful precisely because they’re dangerous; gate them behind your client’s tool-approval prompt rather than auto-approving.

Provisioning & the rest

cloud_tokens stores Hetzner and DigitalOcean API tokens; hetzner can list locations, server types, and images, and create a server — so “spin up a box and connect it to Coolify” becomes a two-tool chain with private_keys handling SSH keys. github_apps manages the GitHub integration (including listing repos and branches), teams reads team membership, and search_docs answers how-to questions from an indexed copy of Coolify’s docs.

Recipes

Five workflows where the install pays for itself. All assume the server is registered with a token scoped to the recipe’s needs.

Recipe 1 — Deploy from chat

“Deploy the blog app and tell me when it finishes. If the build fails, show me the last 50 log lines.” The agent resolves “blog” via smart lookup, calls deploy, polls deployment for status, and falls back to application_logs on failure. Token needs deploy. The chat transcript becomes a lightweight deploy log.

Recipe 2 — Restart a crashed service

“plausible.example.com is returning 502 — diagnose and fix.” diagnose_app takes the domain directly, reports container state and recent exit codes, and the agent follows with control restart and a log check to confirm the service came back. This is the recipe that converts skeptics: 3 a.m. triage without opening a dashboard.

Recipe 3 — Env-var update across a project

“Rotate STRIPE_SECRET_KEY across every app in the payments project to this new value, then redeploy the project.” bulk_env_update + redeploy_project in sequence. One caution from the project’s own issue tracker: env vars in Coolify carry build-time vs runtime flags, and getting them wrong is a classic source of “the new value isn’t showing up” confusion — say explicitly whether the variable is needed at build time.

Recipe 4 — Log triage

“Pull the last 100 log lines from the API app, summarize the errors, and check the Coolify docs for what that Traefik error means.” application_logs feeds the raw lines; search_docs grounds the explanation in Coolify’s actual documentation instead of the model’s memory. Requires read:sensitive — logs count as sensitive data in Coolify’s permission model.

Recipe 5 — Provision a new server end-to-end

“Create a Hetzner box in Falkenstein, add it to Coolify with my default SSH key, and validate the connection.” hetzner create_server → private_keys → validate_server. What used to be twenty minutes across two dashboards is one prompt — though we’d still review the server type and location before approving the create call, since it bills real money.

Limits

• Stdio only (community server). There’s no hosted endpoint for the full read-write server; it runs as a local subprocess. The only remote option is Coolify’s built-in /mcp, which is read-only.
• One instance per registration. The server talks to a single COOLIFY_BASE_URL. Managing several Coolify instances means registering the MCP server once per instance under different names (multi-instance support is an open feature request on the repo).
• Summaries by design. List tools intentionally omit detail to protect your context window; agents must chain a get_* call for full objects. This is the right trade, but it means some answers take two tool calls.
• Coolify’s API moves fast. Coolify v4 shipped beta releases for a long time and the API surface still shifts; the MCP project’s issue history shows occasional schema drift (a domains vs fqdn field mismatch, a missing destination_uuid on multi-destination servers). Run @latest and keep Coolify updated; mismatched versions cause most weirdness.
• Writes are real. stop_all_apps stops all your apps. There is no dry-run mode. Keep destructive tools behind your client’s approval prompt and scope tokens so the blast radius matches the workflow.

Troubleshooting

FAQ

Sources

• Primary implementation: github.com/stumason/coolify-mcp (MIT) and its docs site coolify-mcp.stumason.dev
• Coolify project: github.com/coollabsio/coolify and coolify.io
• Coolify API token docs: coolify.io/docs/api-reference/authorization
• Built-in MCP server PR (merged May 2026): coollabsio/coolify#9862
• January 2026 vulnerability disclosure coverage: The Hacker News
• Alternative implementations: wrediam/coolify-mcp-server, felixallistar/coolify-mcp
• Canonical MCP.Directory entry: /servers/coolify
• More servers like this: Awesome MCP Servers (2026)