How do I install Coolify?

Coolify is a local plugin. Install it using npm package: @masonator/coolify-mcp and add the generated configuration snippet to your AI app's MCP config file. Then restart your AI app.

Is Coolify safe to use?

Coolify scored 5.2/10 (moderate risk) in MCP Marketplace's automated security scan. It has 3 high or critical findings to review. It's listed, but review the security report on this page before installing.

What credentials does Coolify need?

Coolify requires the following credentials or environment variables: COOLIFY_ACCESS_TOKEN, COOLIFY_BASE_URL. You can find setup instructions on the server detail page.

What AI apps work with Coolify?

Coolify uses the Model Context Protocol (MCP) and works with any MCP-compatible AI app, including Claude, ChatGPT / Codex, Gemini, Copilot, Cursor, and more.

Back to Browse

Coolify MCP Server

by StuMason

Developer ToolsModerate5.2MCP RegistryLocal

Free

Server data from the Official MCP Registry

42 optimized tools for managing Coolify infrastructure, diagnostics, and docs search

About

42 optimized tools for managing Coolify infrastructure, diagnostics, and docs search

Security Report

5.2

Moderate5.2Moderate Risk

A well-engineered MCP server for Coolify infrastructure management with strong authentication and credential masking. Code is clean with comprehensive test coverage, proper input validation using Zod, and careful API design that prevents credential leakage. Minor findings around error handling and logging are low-severity and do not undermine the server's security posture. Supply chain analysis found 3 known vulnerabilities in dependencies (0 critical, 3 high severity). Package verification found 1 issue.

4 files analyzed · 8 issues found

Security scores are indicators to help you make informed decisions, not guarantees. Always review permissions before connecting any MCP server.

Permissions Required

This plugin requests these system permissions. Most are normal for its category.

HTTP Network Access

Connects to external APIs or services over the internet.

env_vars

Check that this permission is expected for this type of plugin.

What You'll Need

Set these up before or after installing:

Your Coolify API access tokenRequired

Environment variable: COOLIFY_ACCESS_TOKEN

Your Coolify instance URLOptional

Environment variable: COOLIFY_BASE_URL

How to Install

Add this to your MCP configuration file:

{
  "mcpServers": {
    "io-github-stumason-coolify": {
      "env": {
        "COOLIFY_BASE_URL": "your-coolify-base-url-here",
        "COOLIFY_ACCESS_TOKEN": "your-coolify-access-token-here"
      },
      "args": [
        "-y",
        "@masonator/coolify-mcp"
      ],
      "command": "npx"
    }
  }
}

Documentation

View on GitHub

From the project's GitHub README.

Coolify MCP Server

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

Category	Tools
Infrastructure	`get_infrastructure_overview`, `get_mcp_version`, `get_version`, `system` (health, list_resources, enable/disable API)
Diagnostics	`diagnose_app`, `diagnose_server`, `find_issues`
Batch Operations	`restart_project_apps`, `bulk_env_update`, `stop_all_apps`, `redeploy_project`
Servers	`list_servers`, `get_server`, `validate_server`, `server_resources`, `server_domains`
Projects	`projects` (list, get, create, update, delete via action param)
Environments	`environments` (list, get, create, delete via action param)
Applications	`list_applications`, `get_application`, `application` (CRUD + delete_preview), `application_logs`
Databases	`list_databases`, `get_database`, `database` (create 8 types, delete), `database_backups` (CRUD schedules, executions incl. delete)
Services	`list_services`, `get_service`, `service` (create, update, delete)
Control	`control` (start/stop/restart for apps, databases, services)
Env Vars	`env_vars` (CRUD + bulk_update for application, service, and database env vars)
Storages	`storages` (list, create, update, delete persistent/file storages for apps, databases, services)
Scheduled Tasks	`scheduled_tasks` (list, create, update, delete, list_executions, run_once for apps and services)
Deployments	`list_deployments`, `deploy` (incl. wait-to-terminal-status), `deployment` (get, cancel, list_for_app)
Private Keys	`private_keys` (list, get, create, update, delete via action param)
GitHub Apps	`github_apps` (list, get, create, update, delete, list_repos, list_branches)
Teams	`teams` (list, get, get_members, get_current, get_current_members)
Cloud Tokens	`cloud_tokens` (Hetzner/DigitalOcean: list, get, create, update, delete, validate)
Hetzner Cloud	`hetzner` (list_locations, list_server_types, list_images, list_ssh_keys, create_server)
Documentation	`search_docs` (full-text search across Coolify docs)

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.