🚀 Coolify MCP Server (coolify-mcp)

A comprehensive, production-grade Model Context Protocol (MCP) server for Coolify v4 self-hosted PaaS.

Connect AI coding assistants and agents (Claude Desktop, Cursor, Antigravity, Claude Code, Windsurf, Cline, and VS Code) directly to your Coolify instance to orchestrate infrastructure, deploy applications, manage 8 types of databases, handle environment variables, and diagnose logs using natural language.

---

🌟 Why coolify-mcp?

• 🌐 100% Full Coolify v4 API Coverage: 77 verified MCP tools covering Projects, Environments, Servers, Applications, Databases, Docker Compose Services, Deployments, Team Members, and SSH Keys.
• 🔒 Read-Only Safety Guard: Enable --read-only (or COOLIFY_READ_ONLY=true) to let AI assistants audit, monitor, and troubleshoot without any mutating or destructive actions.
• 🗄️ Universal Database Engine Support: Out-of-the-box creation and configuration for PostgreSQL, MySQL, MariaDB, MongoDB, Redis, ClickHouse, Dragonfly, and KeyDB with engine-specific parameter normalization.
• 📊 Dynamic MCP Resources: Native resources (coolify://overview, coolify://servers, coolify://applications, coolify://databases) for zero-token ambient context.
• 💡 DevOps Prompt Templates: Pre-built prompt recipes (diagnose-application, infrastructure-audit, deployment-summary) for autonomous diagnostics and health checks.
• 🐳 Docker & Stdio Transport Ready: Run as a standard Node CLI tool or inside isolated Docker containers with container-to-container network support.

---

🤖 AI Agent Setup Prompt (Copy & Paste)

If you are using an AI coding assistant (like Antigravity, Claude Code, Cursor, Windsurf, or Cline), simply copy and paste the prompt below into your assistant:

Please configure and set up the Coolify MCP server for me from https://github.com/frizikk/coolify-mcp.git.

Follow these steps:
1. Clone the repository:
   git clone https://github.com/frizikk/coolify-mcp.git
2. Install dependencies and build the server:
   cd coolify-mcp && pnpm install && pnpm build
3. Guide me to provide my Coolify instance URL (e.g. https://coolify.my-domain.com or http://localhost:8000) and API Bearer Token (generated in Coolify under Keys & Tokens / Settings -> API).
4. Add the `coolify` server configuration to my MCP client config (e.g., in Claude Desktop `claude_desktop_config.json`, Cursor `~/.cursor/mcp.json`, or Antigravity `~/.gemini/config/mcp_config.json`).
5. Test the connection by calling `coolify_get_version` and `coolify_get_infrastructure_overview` to verify connection to my Coolify instance.

---

🛠️ MCP Tools Reference

The server exposes 77 specialized tools organized across 8 core DevOps domains:

1. System & Infrastructure Overview (4 tools)

Tool	Parameters	Description
coolify_get_version	none	Get running Coolify instance version string.
coolify_get_health	none	Perform health check on Coolify backend.
coolify_list_resources	none	List all resources managed across all projects.
coolify_get_infrastructure_overview	none	Get aggregated health, server status, apps, and databases dashboard.

2. Servers & Nodes Management (8 tools)

Tool	Parameters	Description
coolify_list_servers	none	List all registered servers with reachability and usability flags.
coolify_get_server	uuid	Get detailed server configuration, IP, and settings.
coolify_validate_server	uuid	Validate SSH connection and connectivity to a server.
coolify_get_server_resources	uuid	List all resources deployed to a specific server.
coolify_get_server_domains	uuid	List all active domains and routes on a server.
coolify_create_server	name, ip, port?, user?, private_key_uuid?, proxy_type?	Register a new server node.
coolify_update_server	uuid, name?, description?, ip?, port?	Update server configuration.
coolify_delete_server	uuid	Remove a server from Coolify.

3. Teams & SSH Keys (9 tools)

Tool	Parameters	Description
coolify_list_teams	none	List all teams accessible by token.
coolify_get_current_team	none	Get active authenticated team details.
coolify_get_current_team_members	none	List users and roles in active team.
coolify_get_team	team_id	Get team details by ID.
coolify_get_team_members	team_id	List members of specific team by ID.
coolify_list_private_keys	none	List all registered SSH private keys.
coolify_get_private_key	uuid	Get private key details.
coolify_create_private_key	name, private_key, description?	Register a new SSH private key (Ed25519/RSA).
coolify_delete_private_key	uuid	Delete an SSH private key.

4. Projects & Environments (9 tools)

Tool	Parameters	Description
coolify_list_projects	none	List all projects and environments.
coolify_get_project	uuid	Get project structure and environment list.
coolify_create_project	name, description?	Create a new project.
coolify_update_project	uuid, name?, description?	Update project name or description.
coolify_delete_project	uuid	Delete an empty project.
coolify_list_environments	project_uuid	List environments in a project.
coolify_get_environment	project_uuid, environment_name_or_uuid	Get environment details.
coolify_create_environment	project_uuid, name	Create a new environment (testing, staging).
coolify_delete_environment	project_uuid, environment_name_or_uuid	Delete an environment.

5. Applications (16 tools)

Tool	Parameters	Description
coolify_list_applications	none	List all standalone applications.
coolify_get_application	uuid	Get application configuration, ports, and domains.
coolify_create_application_public_git	project_uuid, server_uuid, environment_name, git_repository, git_branch, build_pack, name?	Deploy from public Git repo.
coolify_create_application_private_git	project_uuid, server_uuid, environment_name, git_repository, git_branch, private_key_uuid, build_pack, name?	Deploy from private Git repo.
coolify_create_application_dockerfile	project_uuid, server_uuid, environment_name, dockerfile, name?	Deploy from raw or base64 Dockerfile.
coolify_create_application_docker_image	project_uuid, server_uuid, environment_name, docker_registry_image_name, docker_registry_image_tag?	Deploy pre-built Docker image.
coolify_update_application	uuid, name?, description?, domains?, build_pack?, ports_exposes?	Update application configuration.
coolify_delete_application	uuid	Delete application and its containers.
coolify_start_application	uuid	Trigger start / deploy of application.
coolify_stop_application	uuid	Stop running application container.
coolify_restart_application	uuid	Restart application container.
coolify_get_application_logs	uuid	Fetch runtime container stdout/stderr logs.
coolify_list_application_envs	uuid	List all environment variables for application.
coolify_set_application_env	uuid, key, value, is_build_time?, is_literal?	Set / create environment variable.
coolify_bulk_set_application_envs	uuid, envs: [{key, value}]	Bulk update multiple environment variables.
coolify_delete_application_env	uuid, env_uuid	Delete an environment variable by UUID.

6. Deployments (5 tools)

Tool	Parameters	Description
coolify_list_deployments	none	List global running and completed deployments.
coolify_list_app_deployments	app_uuid	List deployment history for a specific app.
coolify_get_deployment	deployment_uuid	Get deployment status, commit info, and logs.
coolify_trigger_deployment	uuid?, tag?, force?	Trigger an instant build and deployment.
coolify_cancel_deployment	deployment_uuid	Cancel an in-progress deployment.

7. Databases (14 tools)

Tool	Parameters	Description
coolify_list_databases	none	List all standalone databases.
coolify_get_database	uuid	Get database details and connection strings.
coolify_create_database	type, project_uuid, server_uuid, environment_name, name?, database_name?, database_user?, database_password?, root_password?, is_public?	Create DB (PostgreSQL, MySQL, MariaDB, MongoDB, Redis, ClickHouse, Dragonfly, KeyDB).
coolify_update_database	uuid, name?, description?, is_public?, public_port?	Update database settings.
coolify_delete_database	uuid	Delete database container and volume.
coolify_start_database	uuid	Start database container.
coolify_stop_database	uuid	Stop database container.
coolify_restart_database	uuid	Restart database container.
coolify_get_database_backups	uuid	List backup configurations for database.
coolify_create_database_backup	uuid, frequency, enabled?, save_s3?	Schedule automatic database backups (cron).
coolify_update_database_backup	uuid, backup_uuid, frequency?, enabled?	Update backup schedule settings.
coolify_delete_database_backup	uuid, backup_uuid	Delete backup configuration.
coolify_list_backup_executions	uuid, backup_uuid	List backup run execution history.
coolify_delete_backup_execution	uuid, backup_uuid, execution_uuid	Delete specific backup run artifact.

8. One-Click Services & Docker Compose (12 tools)

Tool	Parameters	Description
coolify_list_services	none	List all one-click services.
coolify_get_service	uuid	Get service metadata, domains, and containers.
coolify_create_service	type, project_uuid, server_uuid, environment_name, name?, description?	Deploy one-click template (Ghost, Plausible, etc.).
coolify_update_service	uuid, name?, description?	Update service settings.
coolify_delete_service	uuid	Delete service stack.
coolify_start_service	uuid	Start service containers.
coolify_stop_service	uuid	Stop service containers.
coolify_restart_service	uuid	Restart service stack.
coolify_list_service_envs	uuid	List service environment variables.
coolify_set_service_env	uuid, key, value	Create/update service environment variable.
coolify_bulk_set_service_envs	uuid, envs: [{key, value}]	Bulk update service environment variables.
coolify_delete_service_env	uuid, env_uuid	Delete a service environment variable.

---

📊 MCP Resources & Prompts

Resources

• coolify://overview — Aggregated real-time summary of all servers, apps, databases, and services.
• coolify://servers — Live list of servers and reachability status.
• coolify://applications — Live status of all applications and URLs.
• coolify://databases — Live status of database containers.

Prompts

• diagnose-application — Automated diagnostic workflow: checks application state, analyzes recent logs, and inspects environment variables.
• infrastructure-audit — Complete infrastructure health check across servers, disk limits, and failed containers.
• deployment-summary — Analyzes recent deployments and surfaces build failures.

---

⚙️ Configuration & Client Setup

Environment Variables

Variable	Description	Default
COOLIFY_BASE_URL	Base URL of your Coolify instance (e.g. https://coolify.example.com)	http://localhost:8000
COOLIFY_API_TOKEN	Coolify API Bearer Token	""
COOLIFY_READ_ONLY	Restrict to non-mutating actions (true/false)	false

---

Client Config Examples

1. Claude Desktop

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "coolify": {
      "command": "node",
      "args": ["/path/to/coolify-mcp/dist/index.js"],
      "env": {
        "COOLIFY_BASE_URL": "https://coolify.yourdomain.com",
        "COOLIFY_API_TOKEN": "your-bearer-token"
      }
    }
  }
}

2. Cursor (~/.cursor/mcp.json or project .cursor/mcp.json)

{
  "mcpServers": {
    "coolify": {
      "command": "node",
      "args": ["/path/to/coolify-mcp/dist/index.js"],
      "env": {
        "COOLIFY_BASE_URL": "https://coolify.yourdomain.com",
        "COOLIFY_API_TOKEN": "your-bearer-token"
      }
    }
  }
}

3. Antigravity (~/.gemini/config/mcp_config.json)

{
  "mcpServers": {
    "coolify": {
      "command": "node",
      "args": ["/path/to/coolify-mcp/dist/index.js"],
      "env": {
        "COOLIFY_BASE_URL": "https://coolify.yourdomain.com",
        "COOLIFY_API_TOKEN": "your-bearer-token"
      }
    }
  }
}

4. Docker Container Mode

docker run -i --rm \
  -e COOLIFY_BASE_URL="http://coolify:8080" \
  -e COOLIFY_API_TOKEN="your-bearer-token" \
  --network coolify-network \
  coolify-mcp:latest

---

🧪 Testing & Verification

The test suite includes unit tests and full end-to-end integration tests executed against a live Dockerized Coolify v4 instance:

# Run all automated unit and integration tests (43 tests)
pnpm test

# Run complete 77-tool live verification suite
pnpm test:verify-live

---

📄 License

Distributed under the MIT License. See LICENSE for details.