Coolify

npm version npm downloads CI Claude Desktop one-click install MCP Registry License: MIT

Manage Coolify through natural language — 42 token-optimized MCP tools for deploying, debugging, and operating your self-hosted PaaS from Claude, Cursor, or any MCP client.

📖 Full docs: coolify-mcp.stumason.dev — install guide, tools reference, architecture, security model, v3 roadmap.

Install

You need a running Coolify v4 instance and an API token (Coolify → Settings → API).

Claude Desktop — one-click: download coolify-mcp.mcpb and drag it into Settings → Extensions. You'll be prompted for your Coolify URL and token — no Node install, no JSON editing.

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

Any MCP client (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"
      }
    }
  }
}

Behind Cloudflare Access or an auth proxy? Add --header "Key: Value" args (repeatable). Cursor, multiple Coolify instances, and proxy setups are covered in the install guide.

Tools

Full reference with parameters and examples: tools docs.

Design

• Token-optimized — consolidated action-param tools keep the tool list at ~6,600 tokens instead of ~43,000 (85% less), so the server doesn't eat your context window before you've asked anything.
• Summaries by default — list_* tools return uuid/name/status projections (90–99% smaller than the raw API, measured against a real 21-app estate); get_* tools fetch full detail for one resource.
• Smart lookup — diagnose_app takes a UUID, name, or domain; diagnose_server takes a UUID, name, or IP.
• Actionable responses — results carry _actions hints (view logs, restart, next page) so the assistant knows the logical next step without extra tokens.
• Verified deploys — deploy with wait: true polls to a terminal status and returns a log tail on failure, instead of "the site returns 200 so it probably worked".

Secure by default

Secrets are masked at the API boundary — a client granted "list" access never sees plaintext credentials unless you explicitly opt in with reveal: true:

• env_vars — variable values return as ***
• system list_resources (full mode) — webhook HMAC secrets, basic-auth and database passwords, internal/external_db_url connection strings, compose bodies, Traefik labels, nested env vars
• deployment get — the raw upstream payload (server settings, log-drain tokens, webhook secrets) never leaves the client; responses are projected

Details: security model.

Example prompts

Give me an overview of my infrastructure
Diagnose my stuartmason.co.uk 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}
Create a staging environment in project {uuid}
Restart all applications in project {uuid}
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

Contributions welcome — see CONTRIBUTING.md and the contributor docs.

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.