@radoriginllc/coolify-mcp

MCP server wrapping the Coolify REST API. Manage deployments, applications, databases, services, and infrastructure from Claude Code or any MCP-compatible client.

Quick Start

Set the variables in the environment that starts your MCP client, then add the server to .mcp.json:

{
  "mcpServers": {
    "coolify": {
      "command": "npx",
      "args": ["-y", "@radoriginllc/coolify-mcp"]
    }
  }
}

Or run directly:

COOLIFY_URL=https://coolify.example.com COOLIFY_API_TOKEN=your-token npx @radoriginllc/coolify-mcp

Environment Variables

| Variable | Required | Description | |----------|----------|-------------| | COOLIFY_URL | Yes | Instance base URL, such as https://coolify.example.com. Do not add /api/v1 or /mcp. | | COOLIFY_API_TOKEN | Yes | API token from Coolify Keys & Tokens > API Tokens |

The server stops with a setup error when either variable is missing or still contains an unresolved ${...} placeholder. The error does not show either value.

Agent Plugins 1.0.0 expands only ${PLUGIN_ROOT} and ${PLUGIN_DATA}. It does not provide a portable secret reference. Do not put an API token in mcp.json, source control, or a plugin cache.

Token safety and permissions

RAD Coolify uses an API token. Coolify Private Keys are SSH keys for server access or deploy keys for private Git repositories. A Private Key is not an API token and must never be supplied as COOLIFY_API_TOKEN.

API tokens are scoped to one team. Choose the smallest set of current permissions that covers the task:

| Permission | Use | | --- | --- | | read | Status checks and ordinary resource reads | | read:sensitive | Add for logs or sensitive fields | | deploy | Add for deployments and deployment lifecycle controls | | write | Add for application, environment, or other resource changes | | root | Complete API control for Coolify administration |

root bypasses API permission checks. Normal deployment work does not need it.

API paths

Normal operations use /api/v1. Version is requested from /api/v1/version. Current health is requested from /api/health, which is outside the /api/v1 prefix. A 404 from that route triggers the legacy /api/v1/healthcheck fallback.

Tools

Health & Version

| Tool | Description | |------|-------------| | coolify_healthcheck | Verify connectivity through root-level /api/health | | coolify_version | Get the Coolify instance version |

Servers

| Tool | Description | |------|-------------| | coolify_list_servers | List all servers managed by Coolify | | coolify_get_server | Get details for a specific server | | coolify_get_server_resources | List all resources on a server |

Projects

| Tool | Description | |------|-------------| | coolify_list_projects | List all projects | | coolify_get_project | Get project details including environments |

Applications

| Tool | Description | |------|-------------| | coolify_list_applications | List all applications | | coolify_get_application | Get full application details | | coolify_start_application | Start a stopped application | | coolify_stop_application | Stop a running application | | coolify_restart_application | Restart an application | | coolify_get_application_logs | Get recent container logs | | coolify_update_application | Update application settings |

Deployments

| Tool | Description | |------|-------------| | coolify_deploy | Trigger a deployment by UUID or tag | | coolify_get_deployment | Get deployment status and logs | | coolify_list_deployments | List recent deployments for an application | | coolify_cancel_deployment | Cancel a queued or in-progress deployment | | coolify_list_running_deployments | List all currently running deployments |

Environment Variables

| Tool | Description | |------|-------------| | coolify_list_env_vars | List environment variables for an application | | coolify_create_env_var | Create a new environment variable | | coolify_update_env_var | Update an existing environment variable (by key) | | coolify_delete_env_var | Delete an environment variable (by env var UUID) |

Env var changes take effect on the next deploy (coolify_deploy), not on restart.

Databases

| Tool | Description | |------|-------------| | coolify_list_databases | List all databases | | coolify_get_database | Get database details | | coolify_start_database | Start a stopped database | | coolify_stop_database | Stop a running database | | coolify_restart_database | Restart a database | | coolify_list_database_backups | List scheduled backup configurations | | coolify_list_backup_executions | List execution history for a scheduled backup |

Services

| Tool | Description | |------|-------------| | coolify_list_services | List all one-click services | | coolify_get_service | Get service details | | coolify_start_service | Start a stopped service | | coolify_stop_service | Stop a running service | | coolify_restart_service | Restart a service |

Resources

| Tool | Description | |------|-------------| | coolify_list_all_resources | List all resources across all servers |

Companion Plugin

For Coolify deployment patterns, troubleshooting guides, and an AI reviewer agent, install rad-coolify-orchestrator — it pairs with this MCP server to give Claude deep Coolify knowledge alongside the operational tools.

Requirements

• Node.js >= 18
• A running Coolify v4 instance with API access enabled

License

Apache-2.0