io.github.StuMason/coolify

Official

by StuMason · TypeScript

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

38 tools for managing Coolify infrastructure, diagnostics, and documentation.

Topics

aiclaudecoolifydevopsmcpmodel-context-protocolself-hostedtypescriptdeploymentinfrastructurepaas

README.md18 KBView on GitHub

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.

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:

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 for apps and services)
Deployments	`list_deployments`, `deploy`, `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)

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

json

{
  "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

bash

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

bash

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:

json

{
  "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.

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

Tool Type	Returns	Use Case
`list_*`	Summaries only (uuid, name, status, etc)	Discovery, finding resources
`get_*`	Full details for a single resource	Deep inspection, debugging
`get_infrastructure_overview`	All resources summarized in one call	Start here to understand your setup

Response Size Comparison

Endpoint	Full Response	Summary Response	Reduction
list_applications	~170KB	~4.4KB	97%
list_services	~367KB	~1.2KB	99%
list_servers	~4KB	~0.4KB	90%
list_application_envs	~3KB/var	~0.1KB/var	97%
deployment get	~13KB	~1KB	92%
deployment list_for_app	~1MB	~4KB	99.6%

HATEOAS-style Response Actions

Responses include contextual _actions suggesting relevant next steps:

json

{
  "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

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

Pagination

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

bash

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

Example Prompts

Getting Started

text

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

Debugging & Monitoring

text

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

text

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

text

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

text

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

text

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

Variable	Required	Default	Description
`COOLIFY_ACCESS_TOKEN`	Yes	-	Your Coolify API token
`COOLIFY_BASE_URL`	No	`http://localhost:3000`	Your Coolify instance URL

Development

bash

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

# Build
npm run build

# Test
npm test

# Run locally
COOLIFY_BASE_URL="https://your-coolify.com" \
COOLIFY_ACCESS_TOKEN="your-token" \
node dist/index.js

Available Tools

Infrastructure

get_version - Get Coolify API version
get_mcp_version - Get coolify-mcp server version (useful to verify which version is installed)
get_infrastructure_overview - Get a high-level overview of all infrastructure (servers, projects, applications, databases, services)

Diagnostics (Smart Lookup)

These tools accept human-friendly identifiers instead of just UUIDs:

diagnose_app - Get comprehensive app diagnostics (status, logs, env vars, deployments). Accepts UUID, name, or domain (e.g., "stuartmason.co.uk" or "my-app")
diagnose_server - Get server diagnostics (status, resources, domains, validation). Accepts UUID, name, or IP address (e.g., "coolify-apps" or "192.168.1.100")
find_issues - Scan entire infrastructure for unhealthy apps, databases, services, and unreachable servers

Servers

list_servers - List all servers (returns summary)
get_server - Get server details
server_resources - Get resources running on a server
server_domains - Get domains configured on a server
validate_server - Validate server connection

Projects

projects - Manage projects with action: list|get|create|update|delete

Environments

environments - Manage environments with action: list|get|create|delete

Applications

list_applications - List all applications (returns summary)
get_application - Get application details
application_logs - Get application logs
application - Create, update, or delete apps with action: create_public|create_github|create_key|create_dockerimage|update|delete
- Deploy from public repos, private GitHub, SSH keys, or Docker images
- Configure health checks (path, interval, retries, etc.)
env_vars - Manage env vars with resource: application, action: list|create|update|delete
control - Start/stop/restart with resource: application, action: start|stop|restart

Databases

list_databases - List all databases (returns summary)
get_database - Get database details
database - Create or delete databases with action: create|delete, type: postgresql|mysql|mariadb|mongodb|redis|keydb|clickhouse|dragonfly
database_backups - Manage backup schedules with action: list_schedules|get_schedule|create|update|delete|list_executions|get_execution
- Configure frequency, retention policies, S3 storage
- Enable/disable schedules without deletion
- View backup execution history
control - Start/stop/restart with resource: database, action: start|stop|restart

Services

list_services - List all services (returns summary)
get_service - Get service details
service - Create, update, or delete services with action: create|update|delete
env_vars - Manage env vars with resource: service, action: list|create|delete
control - Start/stop/restart with resource: service, action: start|stop|restart

Deployments

list_deployments - List running deployments (returns summary)
deploy - Deploy by tag or UUID
deployment - Manage deployments with action: get|cancel|list_for_app (supports lines and page params for paginated log output with logs_meta)

Private Keys

private_keys - Manage SSH keys with action: list|get|create|update|delete

GitHub Apps

github_apps - Manage GitHub App integrations with action: list|get|create|update|delete

Teams

teams - Manage teams with action: list|get|get_members|get_current|get_current_members

Cloud Tokens

cloud_tokens - Manage cloud provider tokens (Hetzner/DigitalOcean) with action: list|get|create|update|delete|validate

Documentation

search_docs - Search Coolify documentation using full-text search. Indexes 1,500+ doc chunks on first call, returns ranked results with titles, URLs, and snippets (~849 tokens for 5 results)

Batch Operations

Power user tools for operating on multiple resources at once:

restart_project_apps - Restart all applications in a project
bulk_env_update - Update or create an environment variable across multiple applications (upsert behavior)
stop_all_apps - Emergency stop all running applications (requires confirmation)
redeploy_project - Redeploy all applications in a project with force rebuild

Why Coolify MCP?

Context-Optimized: Responses are 90-99% smaller than raw API, preventing context window exhaustion
Smart Lookup: Find apps by domain (stuartmason.co.uk), servers by IP, not just UUIDs
Docs Search: Built-in full-text search across Coolify documentation — your AI assistant can look up how-tos and troubleshooting without leaving the conversation
Batch Operations: Restart entire projects, bulk update env vars, emergency stop all apps
Production Ready: 98%+ test coverage, TypeScript strict mode, comprehensive error handling

stumason.dev - Author's site
MCP Registry - Find this server as io.github.StuMason/coolify
Coolify - The open-source & self-hostable Heroku/Netlify/Vercel alternative
Model Context Protocol - The protocol powering AI tool integrations

Contributing

Contributions welcome! Please see CONTRIBUTING.md for guidelines.

License

MIT - see LICENSE for details.

Support

<p align="center"> Built by <a href="https://stumason.dev">Stu Mason</a> · If you find this useful, please ⭐ star the repo! </p>

Install

Configuration

Environment variables

COOLIFY_ACCESS_TOKENrequiredsecret

Your Coolify API access token

COOLIFY_BASE_URL

Your Coolify instance URL

claude_desktop_config.json

{
  "mcpServers": {
    "coolify": {
      "command": "npx",
      "args": [
        "-y",
        "@masonator/coolify-mcp@2.7.3"
      ],
      "env": {
        "COOLIFY_ACCESS_TOKEN": "<YOUR_COOLIFY_ACCESS_TOKEN>",
        "COOLIFY_BASE_URL": "<YOUR_COOLIFY_BASE_URL>"
      }
    }
  }
}

Topics

Coolify MCP Server

Features

Token-Optimized Design

Installation

Prerequisites

Claude Desktop

Claude Code

Cursor

Custom HTTP Headers (Cloudflare Zero Trust, Auth Proxies)

Context-Optimized Responses

Why This Matters

How It Works

Response Size Comparison

HATEOAS-style Response Actions

Recommended Workflow

Pagination

Example Prompts

Getting Started

Debugging & Monitoring

Application Management

Project Setup

Documentation & Help

Teams & Cloud Providers

Environment Variables

Development

Available Tools

Infrastructure

Diagnostics (Smart Lookup)

Servers

Projects

Environments

Applications

Databases

Services

Deployments

Private Keys

GitHub Apps

Teams

Cloud Tokens

Documentation

Batch Operations

Why Coolify MCP?

Related Links

Contributing

License

Support

Install

Configuration