Corelix Platform MCP Server

A Model Context Protocol (MCP) server that enables AI assistants to manage Coolify infrastructure through natural language. Works with both standard Coolify and the corelix-platform addon.

Features

• 151 MCP tools covering all Coolify API endpoints
• Enhanced tools for permissions, resource backups, custom templates, network management, DNS, cluster management, and Docker registry management (when corelix-platform is installed)
• Auto-detection of enhanced features — falls back to core tools for standard Coolify
• Tool annotations — read-only, destructive, and idempotent hints for AI safety
• Retry logic with exponential backoff for transient API failures
• Works with Claude Desktop, Cursor, VS Code Copilot, Kiro IDE, and any MCP-compatible client

Compatibility

Published on npm as @corelix-io/coolify-enhanced-mcp.

| Target | Supported | Notes | |--------|-----------|-------| | Public free corelix-platform | Yes | Works with standard Coolify endpoints plus free addon capabilities when installed | | Corelix cloud platform | Yes | Same MCP server package; platform-specific capabilities depend on enabled APIs | | Enterprise / commercial deployments | Yes | Same package; available tools depend on the target instance edition and feature set |

Corelix Platform

If you want a managed offering instead of self-hosting the addon, use your Corelix account to access the online product documentation and platform onboarding materials.

The MCP package works across all three distribution models:

• self-hosted free/community
• Corelix managed platform
• enterprise/commercial deployments

Positioning vs Coolify's Built-in MCP

Coolify v4.3.x ships its own MCP feature (per-team toggle under Settings → API). The two servers serve different audiences:

| | Coolify built-in MCP | This server (@corelix-io/coolify-enhanced-mcp) | |---|---|---| | Scope | Deploy controls + diagnostics for that team | Full REST API surface + corelix-platform enhanced features | | Distribution | Inside the Coolify UI, on-instance only | npm package, runs anywhere | | Enhanced tools | None | Permissions, resource backups, templates, networks, DNS, clusters, registries | | Multi-instance | No (one Coolify at a time) | Yes (point COOLIFY_BASE_URL at any instance) | | Coexistence | Yes | Yes — registers on separate endpoints; no conflicts |

Both can run simultaneously. The built-in MCP handles quick per-team deploy flows from the Coolify UI; this server is for broader infrastructure management from any AI client.

Quick Start

Prerequisites

• Node.js 18+
• A Coolify instance with API enabled
• An API token (create in Coolify: Settings > Keys & Tokens > API tokens)

Configuration

Claude Desktop

Add to your claude_desktop_config.json:

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

Cursor / VS Code

Add to your MCP settings:

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

Environment Variables

| Variable | Required | Default | Description | |----------|----------|---------|-------------| | COOLIFY_BASE_URL | Yes | — | Coolify instance URL | | COOLIFY_ACCESS_TOKEN | Yes | — | API token with read/write/deploy scopes | | CORELIX_PLATFORM | No | false | Force enable enhanced features | | CORELIX_MCP_TIMEOUT | No | 30000 | API request timeout in milliseconds | | CORELIX_MCP_RETRIES | No | 3 | Number of retry attempts for failed requests |

Available Tools

Core Tools (Standard Coolify)

Servers

| Tool | Description | |------|-------------| | list_servers | List all servers | | get_server | Get server details | | get_server_resources | Get resources on a server | | get_server_domains | Get domains for a server | | validate_server | Validate server connectivity | | create_server | Register a new server | | update_server | Update server settings | | delete_server | Delete a server |

Projects & Environments

| Tool | Description | |------|-------------| | list_projects | List all projects | | get_project | Get project details | | create_project | Create a project | | update_project | Update project settings | | delete_project | Delete a project | | list_environments | List environments in a project | | get_environment | Get environment details | | create_environment | Create an environment | | delete_environment | Delete an environment |

Applications

| Tool | Description | |------|-------------| | list_applications | List all applications | | get_application | Get application details | | create_application | Create from public git repo | | update_application | Update application settings | | delete_application | Delete an application | | start_application | Start/deploy | | stop_application | Stop | | restart_application | Restart | | get_application_logs | Get container logs | | get_preview_logs | Get logs from a pull-request preview deployment | | deploy | Deploy by UUID or tag |

Databases

| Tool | Description | |------|-------------| | list_databases | List all databases | | get_database | Get database details | | create_database | Create (postgres, mysql, mariadb, mongodb, redis, clickhouse, dragonfly, keydb) | | update_database | Update settings | | delete_database | Delete with cleanup options | | start_database | Start | | stop_database | Stop | | restart_database | Restart | | get_database_logs | Get container logs |

Services

| Tool | Description | |------|-------------| | list_services | List all services | | get_service | Get service details | | create_service | Create one-click or compose service | | update_service | Update settings | | delete_service | Delete with cleanup options | | start_service | Start/deploy | | stop_service | Stop | | restart_service | Restart | | get_service_logs | Get service container logs |

Deployments

| Tool | Description | |------|-------------| | list_deployments | List running deployments | | get_deployment | Get deployment details | | cancel_deployment | Cancel a deployment | | list_app_deployments | Deployment history for an app |

Environment Variables

| Tool | Description | |------|-------------| | list_app_envs / list_service_envs | List env vars | | create_app_env / create_service_env | Create env var | | update_app_env / update_service_env | Update env var | | bulk_update_app_envs / bulk_update_service_envs | Bulk update | | delete_app_env / delete_service_env | Delete env var |

Database Backups

| Tool | Description | |------|-------------| | list_db_backups | List backup configs | | create_db_backup | Create scheduled backup | | update_db_backup | Update backup config | | delete_db_backup | Delete backup config | | list_db_backup_executions | List execution history |

Security & Teams

| Tool | Description | |------|-------------| | list_private_keys | List SSH keys | | get_private_key | Get key details | | create_private_key | Store new SSH key | | delete_private_key | Delete SSH key | | list_teams | List teams | | get_current_team | Get current team | | get_team_members | Get team members |

System

| Tool | Description | |------|-------------| | get_version | Coolify version | | health_check | Instance health (GET /health, outside /api/v1) | | list_resources | All resources |

Enhanced Tools (corelix-platform addon)

These tools are automatically available when the corelix-platform addon is detected.

Granular Permissions

| Tool | Description | |------|-------------| | list_project_access | List users with project access | | grant_project_access | Grant access with permission level | | update_project_access | Change permission level | | revoke_project_access | Revoke access | | check_user_permission | Check specific permission |

Resource Backups

| Tool | Description | |------|-------------| | list_resource_backups | List backup schedules | | create_resource_backup | Create volume/config/full backup | | get_resource_backup | Get schedule + executions | | trigger_resource_backup | Trigger immediate backup | | delete_resource_backup | Delete backup schedule |

Custom Templates

| Tool | Description | |------|-------------| | list_template_sources | List GitHub template sources | | create_template_source | Add template repository | | get_template_source | Get source details | | update_template_source | Update source settings | | delete_template_source | Remove template source | | sync_template_source | Sync from GitHub | | sync_all_templates | Sync all sources |

Network Management

| Tool | Description | |------|-------------| | list_server_networks | List managed networks | | create_network | Create shared network | | get_network | Get network details | | delete_network | Delete network | | sync_networks | Sync from Docker | | migrate_proxy | Proxy isolation migration | | cleanup_proxy | Cleanup old proxy networks | | list_resource_networks | Networks for a resource | | attach_resource_network | Attach to network | | detach_resource_network | Detach from network |

DNS Management

With the default wildcard routing mode, an app deployed under a managed domain needs no DNS tool call at all — the wildcard CNAME + tunnel ingress already cover it and reconcile hooks mark it synced automatically. Only a distinct/custom apex (pin) or a non-wildcard domain needs an explicit call.

| Tool | Description | |------|-------------| | list_dns_providers | List DNS/ingress providers (masked credentials) | | create_dns_provider | Add a provider (cloudflare_tunnel) | | update_dns_provider | Update name/credentials/active | | delete_dns_provider | Delete a provider | | test_dns_provider | Test credentials + API scopes | | list_domains | List managed domains | | create_domain | Add + provision a managed domain | | update_domain | Update routing mode / defaults | | delete_domain | Remove a managed domain | | sync_domain | Re-provision tunnel + records + cloudflared | | list_domain_hostnames | Hostnames under a domain with sync state | | get_resource_dns_status | Resolved hostnames + reconcile state for a resource | | resync_resource_dns | Queue a DNS reconcile (rarely needed) | | assign_resource_domain | [Pro] Pin/unpin a hostname to a specific domain | | list_domain_environment_bindings | [Pro] List environment bindings | | create_domain_environment_binding | [Pro] Bind domain to environment or role bucket | | delete_domain_environment_binding | [Pro] Remove a binding |

Cluster Management [Pro]

| Tool | Description | |------|-------------| | list_clusters | List Swarm clusters | | get_cluster | Get cluster details + metadata | | create_cluster | Register a cluster from a Swarm manager | | update_cluster | Update name, description, or manager server | | delete_cluster | Delete a cluster | | sync_cluster | Force metadata sync from manager | | get_cluster_nodes | List nodes with role, status, resources | | node_action | Drain, activate, promote, demote, label nodes | | remove_node | Remove a node (optional force) | | get_cluster_services | List Swarm services | | get_service_tasks | Tasks for a service | | scale_service | Scale replicas | | rollback_service | Roll back to previous version | | force_update_service | Force re-pull and redeploy | | get_cluster_events | Event stream with filters | | get_cluster_visualizer | Topology/visualizer data | | list_secrets | List Swarm secrets (values never returned) | | create_secret | Create a Swarm secret | | remove_secret | Remove a Swarm secret | | list_configs | List Swarm configs | | create_config | Create a Swarm config | | remove_config | Remove a Swarm config |

Docker Registry Management [Pro]

| Tool | Description | |------|-------------| | list_registries | List team registries (credentials masked) | | create_registry | Add a registry (Docker Hub, GHCR, ECR, etc.) | | get_registry | Get registry details (credentials masked) | | update_registry | Update name, credentials, or active flag | | delete_registry | Delete a registry | | test_registry_connection | Test credentials against registry V2 API | | sync_registry | Push credentials to all team servers | | get_registry_sync_status | Per-server sync status | | sync_all_registries | Sync all active registries |

Development

cd mcp-server
npm install
npm run build
npm start

License

MIT