# coolify-mcp-server

An MCP (Model Context Protocol) server that lets an LLM manage a self-hosted [Coolify](https://coolify.io) instance — applications, databases, services, servers, projects/environments, deployments, environment variables, tags, teams, private keys, and S3 backup storages.

Runs locally over stdio (no hosting required) and talks to your Coolify instance's REST API (`/api/v1`).

## Scope

This covers Coolify's core day-to-day resource management (~81 tools). It intentionally does **not** cover: cloud-provider provisioning catalogs (DigitalOcean/Hetzner/Vultr regions/sizes), GitHub/GitLab App registration, notification-channel config, cloud-init scripts, scheduled tasks, resource storages/volumes/backups, cloning/migration, or webhook secret management. Those can be added later following the same pattern in `src/tools/`.

## Setup

```bash
bun install
```

Set two environment variables when running the server:

- `COOLIFY_BASE_URL` — your Coolify instance URL, e.g. `https://coolify.example.com` (the `/api/v1` suffix is added automatically if missing).
- `COOLIFY_API_TOKEN` — an API token generated in Coolify under **Keys & Tokens → API tokens**.

## Register with Claude Code

Add to your Claude Code MCP config (global `~/.claude.json` or project `.mcp.json`):

```json
{
  "mcpServers": {
    "coolify": {
      "command": "bun",
      "args": ["run", "G:/PROJECTS/coolify-mcp-server/src/index.ts"],
      "env": {
        "COOLIFY_BASE_URL": "https://coolify.k79.quest",
        "COOLIFY_API_TOKEN": "your-api-token-here"
      }
    }
  }
}
```

Or via the CLI:

```bash
claude mcp add coolify --scope user -- bun run G:/PROJECTS/coolify-mcp-server/src/index.ts
```

(then set `COOLIFY_BASE_URL`/`COOLIFY_API_TOKEN` in that config entry's `env`).

## Development

```bash
bun run typecheck   # tsc --noEmit
bun run dev          # bun --watch src/index.ts
```

`scripts/smoke-test.ts` spawns the server over stdio and calls tools against a real Coolify instance — useful when adding new tools:

```bash
COOLIFY_BASE_URL=https://coolify.k79.quest COOLIFY_API_TOKEN=... \
  bun run scripts/smoke-test.ts coolify_list_projects coolify_list_applications
```

## Security notes

- `coolify_list_env_vars` and related tools return environment variable values in plaintext, including secrets — this mirrors Coolify's own API. Treat conversations that call these tools accordingly.
- `coolify_create_private_key` and `coolify_create_s3_storage` transmit key/credential material to your Coolify instance over `COOLIFY_BASE_URL`.
- The API token is a Bearer credential with whatever scope you granted it in Coolify; this server does not add its own authorization layer beyond what the token permits.

## Project layout

```
src/
  index.ts          # entry point, registers all tool modules, stdio transport
  client.ts          # authenticated fetch wrapper + error formatting
  constants.ts        # env-derived config
  schemas.ts          # shared Zod field groups (application/database creation, resource-type enum)
  tool-helpers.ts      # registerCoolifyTool: shared request/response/error wiring for every tool
  tools/
    applications.ts
    databases.ts
    services.ts
    servers.ts
    projects.ts        # projects + environments
    envs.ts            # environment variables (shared across application/service/database)
    tags.ts             # global tags + per-resource tag assignment
    deployments.ts
    teams.ts
    keys.ts              # SSH private keys
    storages.ts           # S3 backup storages
    misc.ts                # /resources, /version, /health
```