# 🚀 Coolify MCP Server (`coolify-mcp`)

[![TypeScript](https://img.shields.io/badge/TypeScript-5.7+-3178C6?style=flat&logo=typescript)](https://www.typescriptlang.org)
[![Node Version](https://img.shields.io/badge/Node.js-18+-339933?style=flat&logo=node.js)](https://nodejs.org)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Model Context Protocol](https://img.shields.io/badge/MCP-Standard-purple.svg)](https://modelcontextprotocol.io)
[![Coolify API](https://img.shields.io/badge/Coolify%20API-v4-blue.svg)](https://coolify.io)
[![Tools](https://img.shields.io/badge/Tools-77%20Verified-brightgreen.svg)](#%EF%B8%8F-mcp-tools-reference)

A comprehensive, production-grade [Model Context Protocol (MCP)](https://modelcontextprotocol.io) server for **[Coolify v4](https://coolify.io)** 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:

```markdown
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`:
```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`)
```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`)
```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
```bash
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:

```bash
# 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.