MCP Server Free

Manage your Coolify infrastructure through natural language using AI assistants like Claude, Cursor, or VS Code Copilot.

Overview

The Corelix Platform MCP Server implements the Model Context Protocol (MCP) — an open standard that lets AI assistants interact with external tools. It wraps all Coolify API endpoints as MCP tools, enabling commands like:

• "List all my applications"
• "Deploy the staging environment"
• "Show me server resource usage"
• "Create a backup schedule for the production database"
• "Grant John deploy access to the Marketing project"

The server provides 148 tools covering servers, projects, applications, databases, services, deployments, backups, DNS, and more.

Prerequisites

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

Quick Start

No installation required — run directly via npx:

npx @amirhmoradi/coolify-enhanced-mcp

Client Configuration

Claude Desktop

Add to your claude_desktop_config.json:

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

Cursor / VS Code / Kiro IDE

Add to your MCP settings:

{
  "mcpServers": {
    "coolify": {
      "command": "npx",
      "args": ["-y", "@amirhmoradi/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	—	Your Coolify instance URL
COOLIFY_ACCESS_TOKEN	Yes	—	API token with read/write/deploy scopes
CORELIX_PLATFORM	No	auto-detected	Force enable enhanced tools
CORELIX_MCP_TIMEOUT	No	30000	API request timeout (ms)
CORELIX_MCP_RETRIES	No	3	Retry attempts for transient failures

Available Tools

Core Tools (72 tools — any Coolify instance)

Category	Tools	Examples
Servers	8	List, create, update, delete, validate, get resources/domains
Projects & Environments	9	CRUD for projects and environments
Applications	10	CRUD, start/stop/restart, logs, deploy
Databases	8	CRUD, start/stop/restart (postgres, mysql, redis, etc.)
Services	8	CRUD, start/stop/restart for one-click services
Deployments	4	List, details, cancel, deployment history
Environment Variables	10	CRUD for app and service env vars, bulk update
Database Backups	5	Backup config and execution management
Security & Teams	7	SSH keys, teams, team members
System	3	Version, health check, resource listing

Enhanced Tools (71 tools — requires Corelix)

Category	Tools	Examples
Permissions	5	Grant/revoke project access, check permissions
Resource Backups	5	Volume/config/full backup schedules
Custom Templates	7	Template source CRUD, sync operations
Networks	10	Network CRUD, resource attachment, proxy migration
DNS	17	Provider/domain CRUD, resource hostname status, re-sync
Clusters	20	Swarm dashboard, nodes, services, secrets (Pro)
Registries	7	Docker registry CRUD, sync, ECR refresh (Pro)

Feature Auto-Detection

The MCP server automatically detects whether Corelix is installed. If it is, enhanced tools are registered automatically based on enabled features. If not, only the 72 core tools are available — no configuration needed.

To force-enable enhanced tools (e.g., if auto-detection fails):

CORELIX_PLATFORM=true

Tool Safety Annotations

Every tool includes safety annotations that help AI clients make decisions:

Annotation	Meaning
readOnlyHint	Tool only reads data, no side effects
destructiveHint	Tool may delete or irreversibly modify resources
idempotentHint	Repeated calls with same arguments are safe

For example, list_applications has readOnlyHint: true, while delete_application has destructiveHint: true. AI clients use these to decide whether to ask for confirmation.

Example Conversations

Deploying an application:

"Deploy my blog application" → AI calls list_applications, finds the blog, calls deploy with its UUID

Checking server health:

"How are my servers doing?" → AI calls list_servers and health_check, presents a summary

Managing permissions:

"Give Sarah deploy access to the Marketing project" → AI calls list_projects to find Marketing, get_team_members to find Sarah, then grant_project_access

Creating a backup:

"Set up daily backups for the production database at 2 AM" → AI calls list_databases, then create_resource_backup with a cron schedule

Retry & Error Handling

The server automatically retries on transient failures:

• HTTP 429 (rate limit) — retries with exponential backoff
• HTTP 5xx (server error) — retries up to 3 times
• Network errors — retries with increasing delays

All tool failures return descriptive error messages to the AI client.

Compatibility

The MCP server works with:

• Standard Coolify v4 (core tools only)
• Corelix community edition (all tools)
• Corelix cloud platform (all tools)
• Enterprise/commercial deployments (all tools)