Skip to content
Back to search

coolify-mcp

MCP server for Coolify — 42 optimized tools for managing self-hosted PaaS through AI assistants

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/StuMason/coolify-mcp with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/StuMason/coolify-mcp'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/stumason--coolify-mcp/badge.svg)](/listings/stumason--coolify-mcp)

HTML

<a href="/listings/stumason--coolify-mcp"><img src="/api/listings/stumason--coolify-mcp/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

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`](https://github.com/StuMason/coolify-mcp/releases/latest/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](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](docs/doctor.md).

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](docs/http-mode.md#coolify-behind-cloudflare-access).

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 172 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. # Coolify MCP Server
  2. [![npm version](https://img.shields.io/npm/v/@masonator/coolify-mcp.svg)](https://www.npmjs.com/package/@masonator/coolify-mcp)
  3. [![npm downloads](https://img.shields.io/npm/dm/@masonator/coolify-mcp.svg)](https://www.npmjs.com/package/@masonator/coolify-mcp)
  4. [![CI](https://github.com/StuMason/coolify-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/StuMason/coolify-mcp/actions/workflows/ci.yml)
  5. [![Claude Desktop one-click install](https://img.shields.io/badge/Claude%20Desktop-one--click%20install-d97757)](https://github.com/StuMason/coolify-mcp/releases/latest/download/coolify-mcp.mcpb)
  6. [![MCP Registry](https://img.shields.io/badge/MCP%20Registry-io.github.StuMason%2Fcoolify-blue)](https://registry.modelcontextprotocol.io)
  7. [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
  8. [![Sponsor](https://img.shields.io/badge/Sponsor-%E2%9D%A4-ea4aaa)](https://github.com/sponsors/StuMason)
  9. Manage [Coolify](https://coolify.io/) 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.
  10. 📖 **[coolify-mcp.stumason.dev](https://coolify-mcp.stumason.dev)** · [Tool reference](docs/tools.md) · [Prompts and resources](docs/prompts-and-resources.md) · [Remote / HTTP mode](docs/http-mode.md) · [Fleet](docs/fleet.md) · [Doctor](docs/doctor.md) · [Safety and security](docs/security.md) · [Changelog](CHANGELOG.md)
  11. ## Install
  12. 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.
  13. **Claude Desktop, one-click.** Download [`coolify-mcp.mcpb`](https://github.com/StuMason/coolify-mcp/releases/latest/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.
  14. **Locally, in any MCP client.** Claude Code:
  15. ```bash
  16. claude mcp add coolify \
  17. -e COOLIFY_BASE_URL="https://your-coolify-instance.com" \
  18. -e COOLIFY_ACCESS_TOKEN="your-api-token" \
  19. -- npx @masonator/coolify-mcp@latest
  20. ```
  21. Codex CLI is the same with `codex mcp add` and `--env`. For Cursor, Claude Desktop or anything that takes a JSON config:
  22. ```json
  23. {
  24. "mcpServers": {
  25. "coolify": {
  26. "command": "npx",
  27. "args": ["-y", "@masonator/coolify-mcp"],
  28. "env": {
  29. "COOLIFY_BASE_URL": "https://your-coolify-instance.com",
  30. "COOLIFY_ACCESS_TOKEN": "your-api-token"
  31. }
  32. }
  33. }
  34. }
  35. ```
  36. **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](docs/http-mode.md).
  37. ### Then run doctor
  38. Whatever you configured, verify it in one command:
  39. ```bash
  40. COOLIFY_BASE_URL="https://your-coolify-instance.com" COOLIFY_ACCESS_TOKEN="your-api-token" \
  41. npx @masonator/coolify-mcp doctor
  42. ```
  43. 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](docs/doctor.md).
  44. ### Behind a proxy or Cloudflare Access
  45. 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](docs/http-mode.md#coolify-behind-cloudflare-access).
  46. ## What it does
  47. Every tool takes an `action`; run one with no arguments and it lists what it accepts. The [tool reference](docs/tools.md) has the full table. In short:
  48. - **Work out what is wrong.** `diagnose_app` and `diagnose_server` take a name, domain, IP or UUID; `find_issues` scans the estate; `logs` reads any container.
  49. - **Deploy and roll back.** `deploy` waits for a terminal status and returns the log tail on failure. Start, stop and restart anything with `control`.
  50. - **Create and destroy.** Applications, databases (8 engines), services, projects and environments, with `environments verify_app` to prove a binding before you mutate it.
  51. - **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.
  52. - **Move across the whole estate.** `bulk_env_update`, `redeploy_project`, `stop_all_apps`, each behind a human confirmation that states the blast radius.
  53. - **Search the Coolify docs** with `search_docs`.
  54. 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.
  55. ## Workflows, not just tools
  56. 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](docs/prompts-and-resources.md).
  57. ## Several Coolify instances
  58. 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](docs/fleet.md).
  59. ## Safe to point at production
  60. 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. Locally, a client without elicitation gets only the `confirm` parameter, which the model sets itself; `COOLIFY_MCP_REQUIRE_HUMAN=on` refuses instead. 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](docs/security.md).
  61. 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](docs/tools.md#coolify-version-compatibility).
  62. ## Coolify's own MCP server, and when you want this one
  63. 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.
  64. 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](https://coolify.io/docs/integrations/mcp) for where it has got to. There is also an [official CLI](https://github.com/coollabsio/coolify-cli) if you would rather script than converse.
  65. This server is for the jobs those two do not cover yet.
  66. | | Coolify's built-in `/mcp` | Official CLI | This server |
  67. | ------------------------- | ----------------------------- | --------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
  68. | Where it runs | Inside your Coolify | Your shell | Your machine, or a container inside your Coolify |
  69. | Install | Nothing | One binary | `npx`, a one-click Claude Desktop extension, or a container |
  70. | Transport | Streamable HTTP | Not an MCP server | stdio and HTTP, so it also works in clients that only speak stdio |
  71. | Coolify instances | One | One context at a time | One or many; in fleet mode every tool takes an `instance` |
  72. | Writes | Documented as read-only today | Yes | Yes |
  73. | Before a destructive call | Not applicable | You typed it | Stops and asks you in your own client, naming the blast radius, on clients that support elicitation; fails closed in HTTP mode |
  74. | When something is broken | Not applicable | Shell exit codes | `doctor` names the cause and the one-line fix |
  75. 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.
  76. 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.
  77. ## Example prompts
  78. ```text
  79. Give me an overview of my infrastructure
  80. Diagnose my shop.example.com app
  81. Find any issues in my infrastructure
  82. Deploy application {uuid} and wait for it to finish
  83. Update the DATABASE_URL env var for application {uuid}
  84. Restart all applications in project {uuid} on instance staging
  85. How do I fix a 502 Bad Gateway error in Coolify?
  86. ```
  87. ## Development
  88. ```bash
  89. git clone https://github.com/StuMason/coolify-mcp.git
  90. cd coolify-mcp && npm install
  91. npm run build && npm test
  92. COOLIFY_BASE_URL="https://your-coolify.com" COOLIFY_ACCESS_TOKEN="token" node dist/index.js
  93. ```
  94. 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](evals/README.md). Contributions welcome: [CONTRIBUTING.md](CONTRIBUTING.md) and the architecture and API-gotcha notes in [CLAUDE.md](CLAUDE.md).
  95. ## Work with me
  96. 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.
  97. - **An MCP server for your product.** Give Claude, Cursor and every other AI client a proper way into your API, like this one.
  98. - **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.
  99. - **Work that runs itself.** Jobs on a schedule that sort, check and report, with a person signing off before anything goes out.
  100. 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.
  101. 📮 [hey@stumason.dev](mailto:hey@stumason.dev) · [stumason.dev](https://stumason.dev) · [coolify-mcp.stumason.dev](https://coolify-mcp.stumason.dev/#hire)
  102. ## Privacy Policy
  103. This server collects nothing about you. There is no telemetry, no analytics and
  104. no phone-home, and there is no hosted service behind it.
  105. Your Coolify API token goes to the instance you configured and nowhere else. The
  106. only other outbound requests are a one-off documentation index refresh from
  107. `coolify.io`, which carries a cache validator and no credentials, and in HTTP
  108. mode a credential-free fetch of the connecting client's own metadata document.
  109. Tool results go to your own MCP client, whose privacy policy governs what
  110. happens next. The audit log writes to your own stderr and never contains token
  111. values.
  112. Full detail, including where in the code each claim is implemented, is in
  113. [PRIVACY.md](PRIVACY.md).
  114. ## Links
  115. - [Coolify](https://coolify.io/): the open-source, self-hostable PaaS this server drives
  116. - [MCP Registry](https://registry.modelcontextprotocol.io): listed as `io.github.StuMason/coolify`
  117. - [laravel-coolify](https://github.com/StuMason/laravel-coolify): deploy Laravel to Coolify with a dashboard, Artisan commands, and generated Dockerfiles
  118. - [Model Context Protocol](https://modelcontextprotocol.io/)
  119. MIT © [Stu Mason](https://stumason.dev). If this is useful, ⭐ the repo. If it saved you an evening, [sponsor a coffee](https://github.com/sponsors/StuMason).

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.