🚀 Coolify MCP Server (`coolify-mcp`)

TypeScript Node Version License: MIT Model Context Protocol Coolify API Tools

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.

🚀 Coolify MCP Server (coolify-mcp)

🌟 Why coolify-mcp?