Coolify MCP Server

To prevent accidental damage, the server implements several safety mechanisms:

Elicitation (Human-in-the-loop)

On clients that support elicitation (like Claude Code and VS Code Copilot), destructive operations will pause and ask for human confirmation. The prompt will explicitly state the "blast radius" (e.g., how many apps will be taken down).

Operations requiring confirmation:

• stop_all_apps, redeploy_project, restart_project_apps
• system disable_api
• Deleting applications, databases, services, projects, or environments
• Deleting credentials (private_keys, cloud_tokens, github_apps)
• bulk_env_update across more than three apps

Note on Volumes: When deleting a resource, the delete_volumes flag defaults to true in the upstream API. You must explicitly manage this if you wish to keep persistent data.

Disabling Confirmations

If your client claims to support elicitation but does not implement it, you can bypass the prompts by setting the environment variable: COOLIFY_MCP_ELICITATION=off

Troubleshooting Timeouts

If a confirmation dialog times out, it is likely due to the MCP client's request timeout (default is often 60 seconds). You may need to increase your client's MCP tool timeout to allow time for human input.

To use the Coolify MCP server, you must have a running Coolify v4 instance and an API token (found in Coolify → Settings → API).

Claude Desktop (One-click)

Download the coolify-mcp.mcpb file and drag it into Settings → Extensions. You will be prompted to provide your Coolify URL and API token.

Claude Code

Use the claude mcp add command with the required environment variables:

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 Configuration)

Add the following configuration to your MCP settings file. If your Coolify instance is behind Cloudflare Access or an auth proxy, you can add repeatable --header "Key: Value" arguments to the args array.

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

The Coolify MCP Server provides a set of tools categorized by functional capabilities. Instead of managing individual tool names, the server is designed around these high-level operational domains:

• Work out what is wrong: Diagnose applications or servers, read container logs, and scan the entire estate for issues.
• Deploy and roll back: Trigger deployments via tag or UUID, monitor deployment progress, cancel deployments, and manage the lifecycle (start, stop, restart) of resources.
• Create and destroy: Manage the lifecycle of Applications, databases, services, projects, and environments.
• Handle the configuration: Manage environment variables, volumes, scheduled tasks, backups, and SSH keys. Note that secrets are masked by default.
• Move across the whole estate: Perform bulk operations across multiple apps, redeploy projects, or stop all resources simultaneously (these actions require human confirmation).

The Coolify MCP server uses tool annotations to communicate the nature of each tool to the client. This allows clients to decide if a tool call requires human confirmation.

Tools are categorized into several safety levels:

• Read-only: Tools that do not modify the environment (e.g., list_servers, get_application).
• Destructive: Tools that perform actions like delete, stop, replace, or cancel (e.g., application, database, control, deploy).
• Non-destructive Writes: Tools that are additive and do not replace or remove existing resources (e.g., hetzner for provisioning servers).
• Idempotent: Tools that can be re-run with the same arguments without additional side effects (e.g., validate_server).

Note: Because tools are consolidated for efficiency, some read-only actions (like env_vars list) are grouped under destructive tool names. This means they may trigger confirmation prompts on some clients even if the specific action is a read.

The Coolify MCP Server is executed via a Node.js environment using stdio transport. It requires specific environment variables to connect to your Coolify instance. You can also provide custom HTTP headers via command-line arguments using the parseHeaders utility (though the specific flag format is determined by the internal parse-headers.js implementation).

Required Environment Variables

• COOLIFY_ACCESS_TOKEN: Your Coolify API access token. This is mandatory.
• COOLIFY_BASE_URL: The base URL of your Coolify instance (defaults to http://localhost:3000).

Configuration Object Structure

The server uses a CoolifyConfig object internally, which maps to these settings:

• baseUrl: The URL of the Coolify instance.
• accessToken: The authentication token.
• customHeaders: An optional object of additional HTTP headers.

# Example setup using environment variables
export COOLIFY_BASE_URL="https://coolify.yourdomain.com"
export COOLIFY_ACCESS_TOKEN="your_secret_token"

# Run the server (assuming it is installed/linked)
npx @masonator/coolify-mcp