coolify-mcp-server

An MCP (Model Context Protocol) server that lets an LLM manage a self-hosted Coolify 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/.

Related MCP server: Coolify MCP Server

Setup

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):

{
  "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:

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

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:

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