Coolify MCP Server

The most comprehensive MCP server for Coolify - 42 optimized tools, smart diagnostics, documentation search, and batch operations for managing your self-hosted PaaS through AI assistants.

📖 Docs: coolify-mcp.stumason.dev — install guide, quickstart, full tools reference, MCP primer, Coolify API gotchas, contributing guide, and the public v3 roadmap.

💡 Building a Laravel app? Check out laravel-coolify — deploy Laravel to Coolify with a Horizon-style dashboard, Artisan commands, and auto-generated Dockerfiles.

A Model Context Protocol (MCP) server for Coolify, enabling AI assistants to manage and debug your Coolify instances through natural language.

Features

This MCP server provides 42 token-optimized tools for debugging, management, and deployment:

Token-Optimized Design

The server uses 85% fewer tokens than a naive implementation (6,600 vs 43,000) by consolidating related operations into single tools with action parameters. This prevents context window exhaustion in AI assistants.

Installation

Prerequisites

• Node.js >= 18
• A running Coolify instance (tested with v4.0.0-beta.460)
• Coolify API access token (generate in Coolify Settings > API)

Claude Desktop

Add to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "coolify": {
      "command": "npx",
      "args": ["-y", "@masonator/coolify-mcp"],
      "env": {
        "COOLIFY_ACCESS_TOKEN": "your-api-token",
        "COOLIFY_BASE_URL": "https://your-coolify-instance.com"
      }
    }
  }
}

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

Note: Use @latest tag (not -y flag) for reliable startup in Claude Code CLI.

Cursor

env COOLIFY_ACCESS_TOKEN=your-api-token COOLIFY_BASE_URL=https://your-coolify-instance.com npx -y @masonator/coolify-mcp

Custom HTTP Headers (Cloudflare Zero Trust, Auth Proxies)

If your Coolify instance sits behind a Cloudflare Access tunnel or other auth-proxy middleware, pass extra headers on every outbound request with --header:

{
  "mcpServers": {
    "coolify": {
      "command": "npx",
      "args": [
        "-y",
        "@masonator/coolify-mcp",
        "--header",
        "CF-Access-Client-Id: abc123.access",
        "--header",
        "CF-Access-Client-Secret: your-secret"
      ],
      "env": {
        "COOLIFY_ACCESS_TOKEN": "your-api-token",
        "COOLIFY_BASE_URL": "https://your-coolify-instance.com"
      }
    }
  }
}

Multiple --header flags can be combined. The reserved headers Authorization and Content-Type are filtered (with a warning) to prevent silently overriding the Coolify bearer token.

Multiple Coolify servers

Each running instance of this MCP server is bound to one Coolify (one COOLIFY_BASE_URL + token). To work with several Coolify instances, pick whichever of these fits your workflow:

Per-workspace config (recommended). Most MCP clients support project-scoped config files (.mcp.json / .cursor/mcp.json / .vscode/mcp.json in the repo root) alongside the global one. Put the Coolify credentials for that project's estate in the project's own config, and "deploy this" automatically routes to the right Coolify whenever you're working in that repo — no server names to remember in conversation.

Named instances in global config. Register the server twice (or more) under distinct names, and address them by name in conversation ("deploy this on staging"):

{
  "mcpServers": {
    "coolify-prod": {
      "command": "npx",
      "args": ["-y", "@masonator/coolify-mcp"],
      "env": {
        "COOLIFY_BASE_URL": "https://prod.coolify.example",
        "COOLIFY_ACCESS_TOKEN": "..."
      }
    },
    "coolify-staging": {
      "command": "npx",
      "args": ["-y", "@masonator/coolify-mcp"],
      "env": {
        "COOLIFY_BASE_URL": "https://staging.coolify.example",
        "COOLIFY_ACCESS_TOKEN": "..."
      }
    }
  }
}

The MCP server itself can't offer a settings screen or auto-detect the current repo — MCP servers are headless child processes and clients don't pass repo context — so routing lives in your client config, where both patterns above work today (see #164).

Context-Optimized Responses

Why This Matters

The Coolify API returns extremely verbose responses - a single application can contain 91 fields including embedded 3KB server objects and 47KB docker-compose files. When listing 20+ applications, responses can exceed 200KB, which quickly exhausts the context window of AI assistants like Claude Desktop.

This MCP server solves this by returning optimized summaries by default.

How It Works

Response Size Comparison

HATEOAS-style Response Actions

Responses include contextual _actions suggesting relevant next steps:

{
  "data": { "uuid": "abc123", "status": "running" },
  "_actions": [
    { "tool": "application_logs", "args": { "uuid": "abc123" }, "hint": "View logs" },
    {
      "tool": "control",
      "args": { "resource": "application", "action": "restart", "uuid": "abc123" },
      "hint": "Restart"
    }
  ],
  "_pagination": { "next": { "tool": "list_applications", "args": { "page": 2 } } }
}

This helps AI assistants understand logical next steps without consuming extra tokens.

Recommended Workflow

1. Start with overview: get_infrastructure_overview - see everything at once
2. Find your target: list_applications - get UUIDs of what you need
3. Dive deep: get_application(uuid) - full details for one resource
4. Take action: control(resource: 'application', action: 'restart'), application_logs(uuid), etc.

Pagination

All list endpoints still support optional pagination for very large deployments:

# Get page 2 with 10 items per page
list_applications(page=2, per_page=10)

Example Prompts

Getting Started

Give me an overview of my infrastructure
Show me all my applications
What's running on my servers?

Debugging & Monitoring

Diagnose my stuartmason.co.uk app
What's wrong with my-api application?
Check the status of server 192.168.1.100
Find any issues in my infrastructure
Get the logs for application {uuid}
What environment variables are set for application {uuid}?
Show me recent deployments for application {uuid}
What resources are running on server {uuid}?

Application Management

Restart application {uuid}
Stop the database {uuid}
Start service {uuid}
Deploy application {uuid} with force rebuild
Update the DATABASE_URL env var for application {uuid}

Project Setup

Create a new project called "my-app"
Create a staging environment in project {uuid}
Deploy my app from private GitHub repo org/repo on branch main
Deploy nginx:latest from Docker Hub
Deploy from public repo https://github.com/org/repo

Documentation & Help

How do I set up Docker Compose with Coolify?
Search the docs for health check configuration
How do I fix a 502 Bad Gateway error?
What are Coolify environment variables?

Teams & Cloud Providers

Who has access to my Coolify instance?
Show me the current team members
List my cloud provider tokens
Validate my Hetzner API token

Environment Variables

Development

```bash

Clone and install

git clone https://github.com/stumason/coolify-mcp.git cd coolify-mcp npm install

Bu