coolify-mcp

# coolify-mcp

[![npm version](https://img.shields.io/npm/v/@fndchagas/coolify-mcp.svg)](https://www.npmjs.com/package/@fndchagas/coolify-mcp)
[![npm downloads](https://img.shields.io/npm/dm/@fndchagas/coolify-mcp.svg)](https://www.npmjs.com/package/@fndchagas/coolify-mcp)
[![license](https://img.shields.io/npm/l/@fndchagas/coolify-mcp.svg)](LICENSE)
[![node version](https://img.shields.io/node/v/@fndchagas/coolify-mcp.svg)](package.json)
[![typescript](https://img.shields.io/badge/TypeScript-5.9.3-3178c6?logo=typescript&logoColor=white)](https://www.typescriptlang.org/)
[![CI](https://github.com/frndchagas/coolify-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/frndchagas/coolify-mcp/actions/workflows/ci.yml)

MCP server for Coolify API - enables full deployment workflows from zero to production.

Targets the **Coolify v4.1.2** API. Types and schemas are generated directly from Coolify's official OpenAPI spec, so tool inputs always match what the API actually accepts.

## Features

- **Full Deployment Workflow**: Create projects, environments, servers, and applications from scratch
- **5 Application Types**: one `createApplication` tool covers public git, GitHub App, Deploy Key, Dockerfile, and Docker Image sources — plus Docker Compose deployments via `createService` (since Coolify v4.1, compose deployments are services)
- **Environment Management**: Full CRUD for environment variables with secret masking
- **Deployment Control**: Deploy (optionally waiting for the terminal status, with a log tail on failure), start, stop, restart applications
- **Diagnostics**: `diagnoseApp` finds an app by UUID, name, or domain and aggregates status, recent deployments, failure log tails, runtime logs, and suggested next actions
- **Docs Search**: `searchDocs` runs full-text search across the official Coolify documentation from a bundled local index — no network needed
- **Security**: Write protection, secret redaction, and MCP annotations (`readOnlyHint`/`destructiveHint`) so clients can auto-approve reads and gate destructive calls
- **Near-full API coverage**: databases (8 engines, backups, envs), services, storages, scheduled tasks, teams, previews, servers, SSH keys, and GitHub Apps
- **Token-efficient**: 65 tools whose definitions cost ~9k tokens of context, with strict runtime validation against schemas generated from Coolify's OpenAPI spec

## Requirements

- Node 18+
- A Coolify API token (Settings > API in your Coolify dashboard)

## Install

**Claude Desktop, one-click:** download [`coolify-mcp.mcpb`](https://github.com/frndchagas/coolify-mcp/releases/latest/download/coolify-mcp.mcpb) from the latest release and drag it into **Settings → Extensions**. You'll be prompted for your Coolify URL and token — no Node install, no JSON editing.

**Via npm:**

```bash
npm install -g @fndchagas/coolify-mcp
# or
npx -y @fndchagas/coolify-mcp
```

## Quick Start

### Claude Code CLI

```bash
claude mcp add coolify \
  --env COOLIFY_BASE_URL="https://coolify.example.com/api/v1" \
  --env COOLIFY_TOKEN="<token>" \
  -- npx -y @fndchagas/coolify-mcp
```

### OpenAI Codex CLI

```bash
codex mcp add coolify \
  --env COOLIFY_BASE_URL="https://coolify.example.com/api/v1" \
  --env COOLIFY_TOKEN="<token>" \
  -- npx -y @fndchagas/coolify-mcp
```

Or edit `~/.codex/config.toml`:

```toml
[mcp_servers.coolify]
command = "npx"
args = ["-y", "@fndchagas/coolify-mcp"]
env = { COOLIFY_BASE_URL = "https://coolify.example.com/api/v1", COOLIFY_TOKEN = "<token>" }
```

### Manual Configuration (`~/.mcp.json`)

```json
{
  "mcpServers": {
    "coolify": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@fndchagas/coolify-mcp"],
      "env": {
        "COOLIFY_BASE_URL": "https://coolify.example.com/api/v1",
        "COOLIFY_TOKEN": "<token>",
        "COOLIFY_ALLOW_WRITE": "true"
      }
    }
  }
}
```

## Environment Variables

| Variable | Default | Description |
|----------|---------|-------------|
| `COOLIFY_BASE_URL` | required | Coolify API URL (e.g., `https://coolify.example.com/api/v1`) |
| `COOLIFY_TOKEN` | required | API token from Coolify Settings > API |
| `COOLIFY_ALLOW_WRITE` | `true` | Enable write operations (create, update, delete, deploy) |
| `COOLIFY_STRICT_VERSION` | `false` | Fail on API version mismatch |
| `COOLIFY_MCP_ELICITATION` | `on` | Set to `off` to skip human confirmation on destructive deletes (escape hatch for clients that advertise elicitation but do not implement it) |
| `MCP_TRANSPORT` | `stdio` | Transport: `stdio`, `http`, `both` |
| `PORT` | `7331` | HTTP port (when using http transport) |
| `MCP_HTTP_TOKEN` | unset | Bearer token required on `/mcp` requests (HTTP transport). Setting it also switches the default bind to `0.0.0.0` |
| `MCP_HTTP_HOST` | `127.0.0.1` (`0.0.0.0` with token) | Interface the HTTP transport binds to. Binding beyond loopback without a token logs a loud warning |

## Deploy from Zero

With this MCP, you can deploy an application from scratch:

```
1. listProjects / createProject       → Get or create a project
2. listEnvironments / createEnvironment → Get or create an environment
3. listServers / createServer         → Get or create a server
4. listPrivateKeys / createPrivateKey → Get or create SSH keys (if needed)
5. createApplication (type: public)   → Create the application
6. applicationEnvs (action: upsert)   → Configure environment variables
7. deploy                             → Trigger deployment
```

## Tools Reference

### Projects & Environments

| Tool | Description | Write |
|------|-------------|-------|
| `listProjects` | List all projects | |
| `createProject` | Create a new project | ✓ |
| `updateProject` | Update project name/description | ✓ |
| `deleteProject` | Delete a project and all its resources | ✓ |
| `listEnvironments` | List environments in a project | |
| `createEnvironment` | Create a new environment | ✓ |

### Servers & Infrastructure

| Tool | Description | Write |
|------|-------------|-------|
| `listServers` | List all servers | |
| `getServer` | Get server details | |
| `createServer` | Create a new server | ✓ |
| `validateServer` | Validate server connection | |
| `listPrivateKeys` | List SSH private keys | |
| `createPrivateKey` | Create a new SSH key | ✓ |
| `listGithubApps` | List configured GitHub Apps | |

### Applications - Read

| Tool | Description |
|------|-------------|
| `listApplications` | List all applications (summarized by default) |
| `getApplication` | Get application details (secrets masked by default) |
| `getLogs` | Get application runtime logs |

### Applications - Create

| Tool | Description | Write |
|------|-------------|-------|
| `createApplication` | Create an application; `type` selects the source: `public`, `private-github-app`, `private-deploy-key`, `dockerfile`, or `dockerimage`. Long-tail fields go in `extra` and are validated per type. | ✓ |

> Docker Compose deployments are created with `createService` passing `docker_compose_raw` — since Coolify v4.1 they are services, not applications.

### Applications - Manage

| Tool | Description | Write |
|------|-------------|-------|
| `updateApplication` | Update application configuration | ✓ |
| `deleteApplication` | Delete an application | ✓ |
| `startApplication` | Start an application | ✓ |
| `stopApplication` | Stop an application | ✓ |
| `restartApplication` | Restart an application | ✓ |

### Environment Variables

| Tool | Description | Write |
|------|-------------|-------|
| `applicationEnvs` | Manage application env vars: list (masked by default), create, update, upsert by key, bulk_update, delete | ✓ |

> Database and service env vars have their own tools: `databaseEnvs` and `serviceEnvs`.

### Deployments

| Tool | Description | Write |
|------|-------------|-------|
| `deploy` | Trigger a deployment; `wait: true` polls to the terminal status and returns a log tail on failure | ✓ |
| `diagnoseApp` | Diagnose an app by UUID, name, or domain: status, recent deployments, failure log tail, runtime logs, hints | |
| `diagnoseServer` | Diagnose a server by UUID, name, or IP: resource status breakdown, domains, hints | |
| `listDeployments` | List running deployments | |
| `getDeployment` | Get deployment status and logs | |
| `listAppDeployments` | List deployments for an application | |
| `cancelDeployment` | Cancel a running deployment | ✓ |

### Databases

| Tool | Description | Write |
|------|-------------|-------|
| `listDatabases` | List all databases | |
| `getDatabase` | Get database details | |
| `createDatabase` | Create a database; `type` selects the engine: postgresql, mysql, mariadb, mongodb, redis, keydb, dragonfly, clickhouse | ✓ |
| `updateDatabase` | Update database configuration | ✓ |
| `deleteDatabase` | Delete a database (volumes/configs deleted by default) | ✓ |
| `controlDatabase` | Start, stop, or restart a database | ✓ |
| `databaseBackups` | Manage backup schedules and executions (list/create/update/delete/list_executions/delete_execution) | ✓ |
| `databaseEnvs` | Manage database env vars (list/create/update/bulk_update/delete) | ✓ |

### Services

| Tool | Description | Write |
|------|-------------|-------|
| `listServices` | List services | |
| `getService` | Get service details (secrets masked by default) | |
| `createService` | Create a one-click service or Docker Compose deployment | ✓ |
| `updateService` | Update a service | ✓ |
| `deleteService` | Delete a service | ✓ |
| `controlService` | Start, stop, or restart a service | ✓ |
| `serviceEnvs` | Manage service env vars (list/create/update/bulk_update/delete) | ✓ |

### Storages, Scheduled Tasks & Previews

| Tool | Description | Write |
|------|-------------|-------|
| `storages` | Manage persistent volumes and file mounts for applications, databases, and services | ✓ |
| `scheduledTasks` | Manage cron tasks for applications and services, including execution history | ✓ |
| `deletePreview` | Delete a preview deployment by pull request id