coolify-mcp

MCP server for managing Coolify instances (v4.3+ API). Control applications, databases, services, servers, and more directly from Claude or any MCP-compatible client.

136 tools | 7 resources | 4 prompts

Requires Coolify v4.3.0 or newer (/api/v1); v4.4.2 is recommended and is the integration-test target for MCP 4.2.0. Tools and options marked v4.4+ need Coolify v4.4.0 or newer and answer 404 or 422 on older instances. Legacy GET-based state-changing endpoints are not supported.

See the 4.2.0 API audit for pinned upstream sources, compatibility changes, and endpoints that are not wrapped. The 4.1.0 audit covers v4.3.23.

Installation

Claude Code

claude mcp add coolify \
  -e COOLIFY_API_URL=http://your-server:8000/api/v1 \
  -e COOLIFY_TOKEN=your-token \
  -- npx mcp-coolify

Codex

codex mcp add coolify \
  --env COOLIFY_API_URL=http://your-server:8000/api/v1 \
  --env COOLIFY_TOKEN=your-token \
  -- npx mcp-coolify

Other MCP clients

COOLIFY_API_URL=http://your-server:8000/api/v1 \
COOLIFY_TOKEN=your-token \
npx mcp-coolify

From source

git clone https://github.com/0xtlt/coolify-mcp
cd coolify-mcp && pnpm install
COOLIFY_API_URL=... COOLIFY_TOKEN=... pnpm start

Claude Desktop

Add to ~/.claude/claude_desktop_config.json:

{
  "mcpServers": {
    "coolify": {
      "command": "pnpm",
      "args": ["exec", "tsx", "/path/to/coolify-mcp/src/index.ts"],
      "env": {
        "COOLIFY_API_URL": "http://your-server:8000/api/v1",
        "COOLIFY_TOKEN": "your-token"
      }
    }
  }
}

Get your API token

Coolify dashboard: Keys & Tokens > API tokens

On Coolify v4.4+ pick the token abilities for what you want to do:

Available Tools

Applications (8)

Preview Deployments (6)

Each tool takes the parent application uuid; all but the list take a pull_request_id between 1 and 2147483647. List, get and deploy need Coolify v4.4+.

Databases (11)

Backup Schedule Updates & Executions (3)

Database Imports (4)

Coolify v4.4+. An import runs in the background: start it, then poll the status tool until status is finished or error. source is s3 (s3_storage_uuid + path), server (absolute path on the database server) or upload (upload_id of a file sent to POST .../imports/uploads).

Services (8)

Servers (8)

Docker Registry Logins (4)

Coolify v4.4+. Coolify runs docker login on the server and does not store the token. registry is a host such as ghcr.io or registry.example.com:5000.

Private Keys (5)

Projects & Environments (9)

Deployments (5)

Application Env Vars (4)

Service Env Vars (4)

Database Env Vars (4)

Storages (12)

Volume Backups (9)

Scheduled Tasks (10)

GitHub Apps (6)

Logs (3)

System (3)

Audit Log (1)

Coolify v4.4+. Requires a team admin/owner API token.

Secret Managers (2)

Coolify v4.4+. After linking, reference secrets in environment variables as {{vault.KEY}}.

Instance Email Settings (2)

Verified on Coolify v4.3.23. Requires a root-team admin/owner API token. Reading secret values requires read:sensitive or root; updating requires write:sensitive.

Teams (5)

Available Resources

Available Prompts

Safety Modes

Log Filtering

The coolify_get_logs, coolify_get_application_preview_logs, coolify_get_database_logs, and coolify_get_service_logs tools support:

• level: Minimum log level (debug, info, warn, error, fatal)
• since/until: ISO 8601 timestamps for time range
• search: Case-insensitive text search
• lines: Server lines to fetch (defaults to limit, up to 10000; "all" or -1 fetches all)
• show_timestamps: Include server timestamps (default true)
• limit: Max filtered entries returned (default 100, max 1000)
• tail: Get most recent logs
• service_name (application and preview logs, v4.4+): Compose service whose container to read

Coolify v4.4+ only serves logs to tokens with the read:sensitive ability.

API Compatibility Notes for 4.2.0

• Logs need `read:sensitive` on Coolify v4.4+. A token with only read gets 403 from every log tool. Create a new token with read:sensitive, or root.
• instant_deploy on application, database and service creation, and on application updates, needs the deploy ability on Coolify v4.4+.
• Servers have a server_role (deployment, build, both). is_build_server still works but is deprecated; sending both with different meanings fails before the request.
• Scheduled task timeout is limited to 1-36000 seconds, as Coolify v4.4 validates it.
• Database start and restart answer 409 while another start, restart or import runs.
• The multipart upload endpoint for imports (POST .../imports/uploads, up to 10 GiB) is not wrapped. Use source: "s3" or source: "server", or upload the file yourself and pass its upload_id.

API Compatibility Notes for 4.1.0

• Storage creation/update no longer accepts host_path. Calls supplying it receive a migration error before contacting Coolify. Use a named type: "persistent" volume, or create type: "file" with fs_path and either is_directory: true or is_host_file: true. Existing mount sources cannot be changed through the update endpoint.
• coolify_create_database_backup now requires frequency and creates a schedule; set backup_now: true to also execute it immediately. The result includes the schedule UUID. Create/update support retention, S3 (s3_storage_uuid), timeout, and missing_backup_notification_days (0 disables alerts). The unsupported update fields s3_storage_id and database_name_prefix have been removed.
• Preview-domain updates replace the entire domain configuration. Supply exactly one of domains (regular app; null clears it) or docker_compose_domains (Compose app; [] clears it).

Environment Variables

Development

pnpm install             # Install dependencies
pnpm run dev             # Watch mode
pnpm run inspect         # MCP Inspector
pnpm run check           # Lint + typecheck + test
pnpm test                # Run tests only

License

MIT