Skip to main content
Glama
hecateq

Coolify MCP Server

by hecateq
OverviewSchemaRelated ServersScoreDiscussions
TypeScript
Hybrid

Coolify MCP Server

A production-grade MCP (Model Context Protocol) server that provides AI agents with secure, controlled access to Coolify infrastructure management.

npm version License: MIT

Table of Contents

  1. Why This MCP Exists

  2. Architecture

  3. Security Model

  4. Coolify API Permissions

  5. Quick Start

  6. Environment Variables

  7. Local stdio Usage

  8. Remote HTTP Usage

  9. Tool Catalog

  10. Operation Modes

  11. Production Safeguards

  12. Docker Usage

  13. Troubleshooting

  14. Development

Related MCP server: mcp-devtools

Why This MCP Exists

Coolify ships its own MCP integration that exposes raw Coolify API resources directly to AI agents. While powerful, that MCP operates as a transparent pass-through to the API, with minimal guardrails between the agent and your production infrastructure.

This MCP is different. It adds a security and policy enforcement layer between the AI agent and Coolify:

Aspect

Coolify Built-in MCP

This MCP Server

Security Model

Direct API token passthrough

Least-privilege token selection, scoped by operation

Operation Modes

None

read-only, deploy-only, safe-write

Access Control

Coolify-native RBAC only

Allowlists by project, environment, and resource UUID

Production Guard

None

Blocks mutations on production environments by default

Audit Trail

Minimal

Structured audit events for every mutation (allowed/denied/error)

Secret Redaction

None

Automatic redaction of tokens, passwords, DB URLs, logs, SSH keys, email addresses

Rate/Scope

Full API surface

42 curated tools grouped into 10 domains: core, GitHub discovery, scheduled tasks, deployments, backups, servers, teams, configuration, storage, and environment variables

This MCP is designed for operational control — letting AI safely observe, deploy, and manage Coolify resources without risking accidental production damage.

Architecture

 ┌──────────────┐     MCP Protocol      ┌──────────────────────────────────────────────────┐
 │              │  (stdio or HTTP SSE)   │                                                  │
 │  AI Agent    │◄──────────────────────►│              Coolify MCP Server                  │
 │  (Claude,    │                        │                                                  │
 │   Copilot,   │     Tool Calls         │  ┌──────────┐  ┌──────────┐  ┌──────────────┐    │
 │   Cursor,    │◄──────────────────────►│  │  Auth &  │─►│ Policy & │─►│   Scope      │    │
 │   OpenCode)  │     JSON Responses     │  │ Token    │  │ Operation│  │  Allowlist   │    │
 │              │                        │  │ Selector │  │ Mode     │  │              │    │
 └──────────────┘                        │  └──────────┘  └────┬─────┘  └──────┬───────┘    │
                                         │                      │               │            │
                                         │  ┌───────────────────▼───────────────▼────────┐  │
                                         │  │           Production Guard                │  │
                                         │  │  (Deny/allow production mutations)        │  │
                                         │  └───────────────────┬────────────────────────┘  │
                                         │                      │                           │
                                         │  ┌───────────────────▼────────────────────────┐  │
                                         │  │  Tool Domains (42 tools across 10 areas)  │  │
                                         │  │                                            │  │
                                         │  │  Core Read (10)   │  GitHub Discovery (3)  │  │
                                         │  │  Actions (11)     │  Scheduled Tasks (4)   │  │
                                         │  │  Servers (5)      │  Backups (2)           │  │
                                         │  │  Teams (2)        │  Configuration (2)     │  │
                                         │  │  Storage (2)      │  Deployments (1)       │  │
                                         │  └───────────────────┬────────────────────────┘  │
                                         │                      │                           │
                                         │  ┌───────────────────▼────────────────────────┐  │
                                         │  │        Coolify API Client                  │  │
                                         │  │  (Token-scoped HTTP requests, redaction)   │  │
                                         │  └───────────────────┬────────────────────────┘  │
                                         │                      │                           │
                                         └──────────────────────┼───────────────────────────┘
                                                                │
                                                       HTTPS (Bearer Token)
                                                                │
                                         ┌──────────────────────▼──────────────────────────┐
                                         │              Coolify Instance                    │
                                         │  (Projects, Resources, Deployments, Envs,       │
                                         │   Servers, Teams, GitHub Apps, Backups,         │
                                         │   Scheduled Tasks, Storage Mounts)              │
                                         └─────────────────────────────────────────────────┘

Security Model

Least-Privilege Tokens

Instead of a single master token, you can configure up to 5 scoped tokens:

Token Env Var

Used For

Example Coolify Token Scopes

COOLIFY_READ_TOKEN

All read operations (list/get resources)

view:projects, view:resources

COOLIFY_SENSITIVE_TOKEN

Reading sensitive data (env vars, logs)

view:envs, view:logs

COOLIFY_WRITE_TOKEN

Write operations (set env vars)

edit:envs

COOLIFY_DEPLOY_TOKEN

Deploy/start/restart operations

deploy:applications

COOLIFY_API_TOKEN

Fallback when no scoped token matches

* (full access)

The server selects the minimum-privilege token for each operation. If COOLIFY_READ_TOKEN is set, list-projects uses it, never the master token.

Secret Redaction

  • Environment variable values are NEVER returned by coolify_list_environment_variables — only keys and metadata.

  • Logs are scanned for Bearer tokens, password, secret, api_key patterns and automatically redacted.

  • The Pino logger has built-in redaction paths for sensitive fields.

  • Audit events do not contain secret values.

Phase 2 Security Controls

With the addition of 21 new tools in Phase 2, the following security controls were added:

Scheduled Task Command Redaction

  • Task command output in coolify_get_task_executions is redacted to prevent command injection visibility.

  • Cron expressions are validated server-side before creation/update.

Path Traversal Prevention (Storage)

  • coolify_create_storage validates source and destination paths against directory traversal patterns (../, ..\\, absolute paths).

  • If a path contains traversal sequences, the operation is denied with a VALIDATION_ERROR.

Field Allowlisting (Configuration Updates)

  • coolify_update_application_config and coolify_update_database_config use PATCH semantics with explicit field allowlisting.

  • Only documented fields can be updated. Arbitrary field injection is blocked.

  • Each update is audited with coolify.application.config.update / coolify.database.config.update events.

Email/SSH Key Redaction

  • coolify_list_team_members gates email addresses behind policy. By default, [REDACTED] is returned.

  • coolify_get_server redacts SSH private keys and sensitive connection details.

  • coolify_list_servers redacts network information (IP addresses, ports).

GitHub Discovery Security

  • coolify_list_github_apps returns no secrets — only UUID, name, organization, and installation metadata.

  • Repository browsing is scoped to what the configured GitHub App can access.

  • All GitHub discovery tools are read-only with no mutation capabilities.

Database Password Protection

  • coolify_create_database never returns generated passwords or connection strings in its response.

  • coolify_list_database_backups redacts destination storage paths.

Additional Protections

  • Timing-safe API key comparison for HTTP transport auth (prevents timing attacks).

  • Scope checking via allowlists before any operation touches a resource.

  • Production guard runs before any mutation.

Coolify API Permissions

The relationship between the Coolify API token permissions and this MCP's tool categories:

Permission Class

Required Coolify Token Scope

MCP Tools

Read

view:projects, view:resources, view:deployments, view:servers, view:teams

All 25 read tools (core + discovery + servers + teams + storage)

Sensitive Read

view:envs, view:logs

coolify_get_application_logs, coolify_list_environment_variables, coolify_get_server, coolify_get_task_executions

Deploy

deploy:applications

coolify_deploy, coolify_restart, coolify_start, coolify_cancel_deployment

Write

edit:envs, operate:applications, operate:servers

All safe-write tools (create project/env/app/service/db, set env vars, create scheduled tasks, create backups, create storage, update configs, validate server)

Stop

operate:applications

coolify_stop (gated by COOLIFY_ALLOW_STOP)

Quick Start

Prerequisites

  • Node.js >= 18

  • A Coolify instance with API tokens configured

  • Coolify API token(s) with appropriate scopes

Option A — Install directly from GitHub (easiest)

# Install as a dependency directly from the public GitHub repo
# (the prepare script builds dist/ automatically)
npm install github:hecateq/mcp-coolify

# Or run it on the fly with npx
npx -y github:hecateq/mcp-coolify

Then configure your MCP client (see Local stdio Usage) with:

{
  "type": "local",
  "command": ["node", "node_modules/mcp-coolify/dist/index.js"],
  "environment": { "COOLIFY_URL": "...", "COOLIFY_API_TOKEN": "..." }
}

Option B — Clone and run locally

# 1. Clone the repository
git clone https://github.com/hecateq/mcp-coolify.git
cd mcp-coolify

# 2. Install dependencies (prepares dist/ automatically)
npm install

# 3. Configure environment
cp .env.example .env
# Edit .env with your Coolify URL and API token

# 4. Run the server (stdio mode — default)
npm start

Test the connection

The server exposes a health tool. In stdio mode, use an MCP client to query:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "coolify_health",
    "arguments": {}
  }
}

Expected response:

{
  "content": [{
    "text": "{\n  \"ok\": true,\n  \"coolifyUrl\": \"[CONFIGURED]\",\n  \"authStatus\": \"authenticated\",\n  \"latencyMs\": 42,\n  \"transport\": \"stdio\"\n}"
  }]
}

Environment Variables

All configuration is via environment variables. Read from src/config/schema.ts via Zod validation.

Required

Variable

Type

Default

Description

COOLIFY_URL

string (URL)

—

Base URL of your Coolify instance (e.g. https://coolify.example.com). Trailing slashes are stripped.

API Tokens (at least one required)

Variable

Type

Default

Description

COOLIFY_API_TOKEN

string

—

Fallback API token (used when no scoped token matches)

COOLIFY_READ_TOKEN

string

—

Read-only token for normal read operations

COOLIFY_SENSITIVE_TOKEN

string

—

Token for reading sensitive data (envs, logs)

COOLIFY_WRITE_TOKEN

string

—

Token for write operations (env vars, settings)

COOLIFY_DEPLOY_TOKEN

string

—

Token for deploy operations

Note: Scoped tokens override COOLIFY_API_TOKEN. The server automatically selects the least-privilege token for each operation.

Transport

Variable

Type

Default

Description

MCP_TRANSPORT

"stdio" | "http"

"stdio"

Transport mode

MCP_HTTP_HOST

string

"0.0.0.0"

HTTP transport host (only used when MCP_TRANSPORT=http)

MCP_HTTP_PORT

number (1–65535)

3000

HTTP transport port

MCP_SERVER_API_KEY

string

—

API key for authenticating HTTP MCP requests (required for HTTP transport)

Operation Mode

Variable

Type

Default

Description

COOLIFY_OPERATION_MODE

"read-only" | "deploy-only" | "safe-write"

"read-only"

Restricts what operations the MCP server allows

Allowlists (Optional)

Variable

Type

Default

Description

COOLIFY_ALLOWED_PROJECT_UUIDS

string (comma-separated identifiers)

—

Restrict access to specific projects. Accepts UUID v4 or Coolify-native identifiers

COOLIFY_ALLOWED_ENVIRONMENT_UUIDS

string (comma-separated identifiers)

—

Restrict access to specific environments. Accepts UUID v4 or Coolify-native identifiers

COOLIFY_ALLOWED_RESOURCE_UUIDS

string (comma-separated identifiers)

—

Restrict access to specific resources. Accepts UUID v4 or Coolify-native identifiers

Production Protection

Variable

Type

Default

Description

COOLIFY_PRODUCTION_ENV_NAMES

string (comma-separated)

"production,prod"

Environment names considered "production"

COOLIFY_DENY_PRODUCTION_MUTATIONS

"true" | "false"

"true"

Block all mutations on production environments

COOLIFY_ALLOW_PRODUCTION_DEPLOY

"true" | "false"

"false"

Allow deploy on production (only if DENY_PRODUCTION_MUTATIONS is false)

COOLIFY_ALLOW_STOP

"true" | "false"

"false"

Allow stop operations (globally)

COOLIFY_ALLOW_ENV_WRITE

"true" | "false"

"false"

Allow environment variable modifications

Logging

Variable

Type

Default

Description

COOLIFY_LOG_MAX_LINES

number (1–1000)

200

Max log lines to return from application logs

LOG_LEVEL

string

"info"

Pino log level ("fatal", "error", "warn", "info", "debug", "trace")

Local stdio Usage (OpenCode)

Add to your opencode.local.jsonc:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "coolify": {
      "type": "local",
      "command": ["node", "/path/to/coolify-mcp/dist/index.mjs"],
      "environment": {
        "COOLIFY_URL": "https://coolify.example.com",
        "COOLIFY_API_TOKEN": "{env:COOLIFY_API_TOKEN}",
        "COOLIFY_OPERATION_MODE": "read-only"
      }
    }
  }
}

A complete example is at examples/opencode.local.jsonc.

Remote HTTP Usage (OpenCode)

When running the MCP server in HTTP mode behind a reverse proxy, configure OpenCode for remote access:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "coolify-remote": {
      "type": "remote",
      "url": "https://coolify-mcp.example.com/mcp",
      "headers": {
        "Authorization": "Bearer {env:MCP_SERVER_API_KEY}"
      }
    }
  }
}

A complete example is at examples/opencode.remote.jsonc.

HTTP Transport Endpoints

Endpoint

Auth Required

Purpose

GET /healthz

No

Liveness check — returns {"ok":true,"status":"alive"}

GET /readyz

No

Readiness check — verifies Coolify API is reachable

POST /mcp

Yes (Bearer)

MCP protocol endpoint — all tool calls go here

Tool Catalog

The server registers 42 tools: 25 read-only tools and 17 action (mutation/deploy) tools.

Note: Tool numbering is for reference only. Tools 1-15 are Phase 1 (original), tools 16-42 are Phase 2 (new).

Read Tools (25)

Core Read Tools (10 — Phase 1)

#

Tool Name

Purpose

Input

Read-Only

Idempotent

1

coolify_health

Check Coolify API and MCP server connectivity. Returns health status, auth status, and latency. No secrets in response.

{}

✅

✅

2

coolify_list_projects

List all Coolify projects with optional name filter.

name? (string)

✅

✅

3

coolify_get_project

Get a single project by UUID with its environments and resource counts.

uuid (resource ID)

✅

✅

4

coolify_list_resources

List all resources with filters.

project_uuid?, environment_uuid?, resource_type? (enum: 7 types), status? (enum: 5 statuses), search? (string)

✅

✅

5

coolify_get_resource

Get a single resource detail by UUID and type. Sensitive fields (DB URLs) redacted.

uuid (resource ID), type (enum: application/service/database)

✅

✅

6

coolify_project_overview

High-level project overview: project info, envs, resources, deployments, health summary. Aggregates 4 API calls into one.

project_uuid (resource ID)

✅

✅

7

coolify_list_deployments

List deployments with filters. Newest first.

resource_uuid?, status? (enum: 5 statuses), limit? (1–50)

✅

✅

8

coolify_get_deployment

Get deployment detail by UUID: status, timestamps, commit info, error summary.

deployment_uuid (string)

✅

✅

9

coolify_get_application_logs

Get application logs (capped by COOLIFY_LOG_MAX_LINES). Secrets redacted.

application_uuid (resource ID), lines? (10–1000)

✅

✅

10

coolify_list_environment_variables

List env vars for a resource. Values are NEVER returned — only keys and metadata.

application_uuid (resource ID)

✅

✅

GitHub Discovery Tools (3 — Phase 2)

#

Tool Name

Purpose

Input

Read-Only

Idempotent

16

coolify_list_github_apps

List GitHub Apps connected to your Coolify instance. Returns team and system-wide apps. No secrets.

{}

✅

✅

17

coolify_list_repositories

List repositories accessible via a GitHub App. Supports pagination and search.

github_app_uuid (resource ID), search? (string), page? (int), limit? (int)

✅

✅

18

coolify_list_branches

List branches of a GitHub repository via a GitHub App.

github_app_uuid (resource ID), owner (string), repository (string)

✅

✅

Scheduled Task Read Tools (2 — Phase 2)

#

Tool Name

Purpose

Input

Read-Only

Idempotent

19

coolify_list_scheduled_tasks

List scheduled tasks for an application or service. Returns task UUID, name, command, schedule, enabled, last execution.

resource_uuid (resource ID), resource_type? (string)

✅

✅

20

coolify_get_task_executions

Get execution history for a scheduled task. Output is redacted for security.

task_uuid (string), resource_uuid? (resource ID), resource_type? (string), status? (string), limit? (1–100)

✅

✅

Backup Read Tool (1 — Phase 2)

#

Tool Name

Purpose

Input

Read-Only

Idempotent

21

coolify_list_database_backups

List backup configurations and executions for a database. Sensitive destination paths are redacted.

database_uuid (resource ID)

✅

✅

Server Read Tools (4 — Phase 2)

#

Tool Name

Purpose

Input

Read-Only

Idempotent

22

coolify_list_servers

List all servers connected to your Coolify instance. Sensitive network info and SSH keys redacted.

{}

✅

✅

23

coolify_get_server

Get a single server detail by UUID. SSH keys and sensitive network info redacted.

uuid (resource ID)

✅

✅

24

coolify_list_server_resources

List resources associated with a specific server.

server_uuid (resource ID), resource_type? (string), status? (string)

✅

✅

25

coolify_list_server_domains

List domains associated with a server.

server_uuid (resource ID)

✅

✅

Team Read Tools (2 — Phase 2)

#

Tool Name

Purpose

Input

Read-Only

Idempotent

26

coolify_get_current_team

Get the current team context: id, name, and permission scope.

{}

✅

✅

27

coolify_list_team_members

List members of the current team. Email addresses policy-gated and redacted by default.

{}

✅

✅

Storage Read Tool (1 — Phase 2)

#

Tool Name

Purpose

Input

Read-Only

Idempotent

28

coolify_list_storages

List storage mounts for an app/service/database. Sensitive host paths redacted.

resource_uuid (resource ID), resource_type (enum: application/service/database)

✅

✅

Configuration Update Tools (2 — Phase 2, safe-write)

#

Tool Name

Purpose

Input

Read-Only

Idempotent

29

coolify_update_application_config

Update application config: health check, resource limits, replicas, ports, build settings. PATCH semantics. Audit: coolify.application.config.update

application_uuid (resource ID), health_check?, cpu_limit?, memory_limit?, replicas?, ports?, etc.

✅ (safe-write)

✅

30

coolify_update_database_config

Update database config: CPU/memory limits, name, description. PATCH semantics. Audit: coolify.database.config.update

database_uuid (resource ID), cpu_limit?, memory_limit?, name?, description?

✅ (safe-write)

✅

Action Tools (17)

Core Deploy Tools (5 — Phase 1)

#

Tool Name

Purpose

Input

Destructive

Idempotent

Policy Checks

11

coolify_deploy

Deploy a resource. Supports force deploy (POST vs GET).

resource_uuid (resource ID), resource_type (enum), force? (bool), environment_name? (string)

❌

✅

Mode + Scope + Production

12

coolify_restart

Restart a resource.

resource_uuid (resource ID), resource_type (enum), environment_name? (string)

⚠️

❌

Mode + Scope + Production

13

coolify_start

Start a stopped resource.

resource_uuid (resource ID), resource_type (enum), environment_name? (string)

❌

✅

Mode + Scope + Production

14

coolify_stop

Stop a resource. Disabled by default — must set COOLIFY_ALLOW_STOP=true. Marked destructive.

resource_uuid (resource ID), resource_type (enum), environment_name? (string)

✅

❌

AllowStop gate + Mode + Scope + Production

15

coolify_set_environment_variable

Set a single env var on a resource. Disabled by default — COOLIFY_ALLOW_ENV_WRITE=true. Value NEVER returned.

resource_uuid (resource ID), key (string 1–256), value (string 1–65536), environment_name? (string)

⚠️

✅

AllowEnvWrite gate + Mode + Scope + Production

New Action Tools (6 — Phase 2, safe-write)

#

Tool Name

Purpose

Input

Destructive

Idempotent

Policy Checks

31

coolify_create_project

Create a new project.

name (string), description? (string)

❌

✅

Mode + Scope + Production

32

coolify_create_environment

Create a new environment within a project.

project_uuid (resource ID), name (string)

❌

✅

Mode + Scope + Production

33

coolify_create_application

Create a new application in a project environment.

project_uuid (resource ID), environment_name (string), name (string), build_pack?, repository?, etc.

❌

✅

Mode + Scope + Production

34

coolify_create_service

Create a new service in a project environment.

project_uuid (resource ID), environment_name (string), name (string), image (string), etc.

❌

✅

Mode + Scope + Production

35

coolify_create_database

Create a new database. Passwords/connection strings NEVER returned.

project_uuid (resource ID), environment_name (string), name (string), database_type (enum: 8 types), etc.

❌

✅

Mode + Scope + Production

36

coolify_set_environment_variables

Set multiple env vars in bulk (1–50). Disabled by default — COOLIFY_ALLOW_ENV_WRITE=true. Values NEVER returned.

resource_uuid (resource ID), resource_type (enum), variables (array of {key, value}), environment_name? (string)

⚠️

✅

AllowEnvWrite gate + Mode + Scope + Production

Deployment Action Tool (1 — Phase 2)

#

Tool Name

Purpose

Input

Destructive

Idempotent

Policy Checks

37

coolify_cancel_deployment

Cancel a queued or in-progress deployment. Returns UNSUPPORTED_OPERATION for terminal states. Audit: coolify.deployment.cancel

deployment_uuid (string)

❌

❌

Mode + Scope

Backup Action Tool (1 — Phase 2, safe-write)

#

Tool Name

Purpose

Input

Destructive

Idempotent

Policy Checks

38

coolify_create_backup_config

Create a backup config for a database. Cron expression validated. Audit: coolify.database_backup_config.create

database_uuid (resource ID), schedule (cron string), destination_uuid? (resource ID), retention? (int), enabled? (bool)

❌

✅

Mode + Scope + Production

Scheduled Task Action Tools (2 — Phase 2, safe-write)

#

Tool Name

Purpose

Input

Destructive

Idempotent

Policy Checks

39

coolify_create_scheduled_task

Create a scheduled task (cron job). Cron expression validated. Audit: coolify.scheduled_task.create

resource_uuid (resource ID), resource_type (enum), name (string), command (string), schedule (cron string), container?, timeout? (int), enabled? (bool)

❌

✅

Mode + Scope + Production

40

coolify_update_scheduled_task

Update a scheduled task.

task_uuid (string), resource_uuid (resource ID), resource_type (enum), name?, command?, schedule? (cron string), enabled? (bool)

❌

✅

Mode + Scope + Production

Server Validation Tool (1 — Phase 2)

#

Tool Name

Purpose

Input

Destructive

Idempotent

Policy Checks

41

coolify_validate_server

Validate server connectivity and configuration. Audited as mutation action.

server_uuid (resource ID)

❌

✅

Mode + Scope

Storage Action Tool (1 — Phase 2, safe-write)

#

Tool Name

Purpose

Input

Destructive

Idempotent

Policy Checks

42

coolify_create_storage

Create a storage mount for a resource. Path traversal validated. Audit: coolify.storage.create

resource_uuid (resource ID), resource_type (enum), storage_type? (string), source? (string), destination (string)

❌

✅

Mode + Scope + Production

Policy Check Chain (Action Tools)

Every action tool runs through the following policy checks before executing:

  1. Allow Gate Check — Some tools have dedicated allow gates: COOLIFY_ALLOW_STOP (for stop), COOLIFY_ALLOW_ENV_WRITE (for env var modifications). If the gate is closed, the operation is denied.

  2. Operation Mode Check — Does the mode (read-only/deploy-only/safe-write) permit this operation?

  3. Scope/Allowlist Check — Is the target resource UUID in the allowed list (if configured)?

  4. Production Guard Check — If the environment_name matches a production pattern, is this mutation allowed?

  5. Input Validation — All inputs are validated via Zod schemas. Cron expressions are validated. Path traversal is prevented for storage operations.

  6. Audit Logging — Every mutation is logged with a structured audit event containing the operation, resource, and result (allowed/denied/error).

If any check fails, the operation is denied with a POLICY_DENIED error code and an audit event is logged.

Common Response Format

All tools return a consistent JSON response structure:

Success:

{
  "ok": true,
  "summary": "Found 3 project(s)",
  "data": [ /* ... */ ],
  "meta": {
    "durationMs": 42,
    "truncated": false
  }
}

Error (policy denied):

{
  "ok": false,
  "summary": "Operation denied by policy",
  "error": {
    "code": "POLICY_DENIED",
    "message": "Operation mode is 'read-only' — 'deploy' operations are not permitted",
    "retryable": false
  },
  "meta": {
    "durationMs": 5
  }
}

Error (upstream):

{
  "ok": false,
  "summary": "Failed to list projects",
  "error": {
    "code": "UPSTREAM_ERROR",
    "message": "Coolify API returned status 500",
    "retryable": true
  },
  "meta": {
    "durationMs": 1203
  }
}

Error Codes

Code

Meaning

Retryable

AUTHENTICATION_FAILED

Token missing or invalid

❌

PERMISSION_DENIED

Token lacks required scope

❌

POLICY_DENIED

Operation blocked by MCP policy (mode/scope/production)

❌

RESOURCE_NOT_FOUND

Coolify resource not found (404)

❌

RATE_LIMITED

Coolify API rate limit hit (429)

✅

COOLIFY_UNAVAILABLE

Coolify instance unreachable or 5xx

✅

REQUEST_TIMEOUT

Request exceeded 30s timeout

✅

VALIDATION_ERROR

Invalid input parameters

❌

UPSTREAM_ERROR

Generic Coolify API error

varies

INTERNAL_ERROR

MCP server internal error

❌

Operation Modes

The COOLIFY_OPERATION_MODE environment variable controls what operations the MCP server permits:

read-only (default)

Safe for monitoring and exploration. Only the 10 read tools are allowed. All 5 action tools return POLICY_DENIED.

Allowed

Denied

All read tools (health, list, get, logs)

All action tools (deploy, restart, start, stop, set env)

deploy-only

Read access plus deploy operations (deploy, restart, start). Write operations (stop, set env vars) are denied.

Allowed

Denied

All read tools

coolify_stop

coolify_deploy

coolify_set_environment_variable

coolify_restart

coolify_start

safe-write

Full read + deploy + write access. Stop and env-write are still gated behind their respective ALLOW_* flags.

Allowed

Gated By

All read tools

—

coolify_deploy

—

coolify_restart

—

coolify_start

—

coolify_stop

COOLIFY_ALLOW_STOP=true

coolify_set_environment_variable

COOLIFY_ALLOW_ENV_WRITE=true

Mode Decision Matrix

Operation

read-only

deploy-only

safe-write

All read tools (25)

✅

✅

✅

coolify_deploy

❌

✅

✅

coolify_restart

❌

✅

✅

coolify_start

❌

✅

✅

coolify_stop

❌

❌

✅ (if ALLOW_STOP)

coolify_set_environment_variable

❌

❌

✅ (if ALLOW_ENV_WRITE)

coolify_set_environment_variables (bulk)

❌

❌

✅ (if ALLOW_ENV_WRITE)

coolify_cancel_deployment

❌

✅

✅

coolify_create_* (project/env/app/service/db)

❌

❌

✅

coolify_create_scheduled_task

❌

❌

✅

coolify_update_scheduled_task

❌

❌

✅

coolify_create_backup_config

❌

❌

✅

coolify_create_storage

❌

❌

✅

coolify_update_application_config

❌

❌

✅

coolify_update_database_config

❌

❌

✅

coolify_validate_server

❌

❌

✅

Production Safeguards

Production Environment Detection

The server defines "production" environments via COOLIFY_PRODUCTION_ENV_NAMES (default: production,prod). When an action tool receives an environment_name parameter, it checks if that name matches any production name (case-insensitive).

Protection Layers

Layer

Env Var

Default

Effect

Deny All Production Mutations

COOLIFY_DENY_PRODUCTION_MUTATIONS

true

Blocks ALL mutations (deploy, restart, start, stop, env write) on production environments

Allow Production Deploy

COOLIFY_ALLOW_PRODUCTION_DEPLOY

false

If DENY_PRODUCTION_MUTATIONS is false, this controls whether deploy is allowed on production

Allow Stop

COOLIFY_ALLOW_STOP

false

Globally disables stop operations. Required for production stop too

Allow Env Write

COOLIFY_ALLOW_ENV_WRITE

false

Globally disables env var modifications. Required for production env writes too

Recommended Production Configuration

# Strict — no mutations on production at all (default)
COOLIFY_OPERATION_MODE=read-only
COOLIFY_DENY_PRODUCTION_MUTATIONS=true
COOLIFY_ALLOW_STOP=false
COOLIFY_ALLOW_ENV_WRITE=false
# Moderate — allow deploys to production, block everything else
COOLIFY_OPERATION_MODE=deploy-only
COOLIFY_DENY_PRODUCTION_MUTATIONS=false
COOLIFY_ALLOW_PRODUCTION_DEPLOY=true
COOLIFY_ALLOW_STOP=false
COOLIFY_ALLOW_ENV_WRITE=false

Docker Usage

Build from source

npm run build

Run with Docker

FROM node:20-alpine
WORKDIR /app
COPY package*.json ./
RUN npm ci --only=production
COPY dist/ ./dist/
EXPOSE 3000
CMD ["node", "dist/index.js"]

Docker Compose

services:
  coolify-mcp:
    build: .
    environment:
      COOLIFY_URL: "https://coolify.example.com"
      COOLIFY_API_TOKEN: "${COOLIFY_API_TOKEN}"
      MCP_TRANSPORT: "http"
      MCP_HTTP_PORT: "3000"
      MCP_SERVER_API_KEY: "${MCP_SERVER_API_KEY}"
      COOLIFY_OPERATION_MODE: "read-only"
    ports:
      - "3000:3000"

Troubleshooting

Server won't start

Symptom: Configuration validation failed: coolifyUrl: Required

Fix: Set COOLIFY_URL environment variable to your Coolify instance URL.

export COOLIFY_URL="https://coolify.example.com"

Symptom: Configuration validation failed: coolifyUrl: Invalid URL

Fix: Ensure COOLIFY_URL is a valid URL including protocol (https://).

Authentication failures

Symptom: AUTHENTICATION_FAILED — "No Coolify API token configured"

Fix: Set at least COOLIFY_API_TOKEN or a scoped token like COOLIFY_READ_TOKEN.

HTTP transport not working

Symptom: MCP_SERVER_API_KEY is required for HTTP transport mode

Fix: Set MCP_SERVER_API_KEY to a strong random key when using MCP_TRANSPORT=http.

# Generate a secure key
openssl rand -hex 32

Production mutations blocked

Symptom: POLICY_DENIED — "Production mutations are denied"

Cause: Environment name matches a production pattern (default: production, prod) and COOLIFY_DENY_PRODUCTION_MUTATIONS is true (the default).

Fix: If intentional, use a non-production environment. To allow production mutations, set COOLIFY_DENY_PRODUCTION_MUTATIONS=false and review the specific allow flags.

Stop operations blocked

Symptom: POLICY_DENIED — "Stop operations are disabled"

Cause: COOLIFY_ALLOW_STOP defaults to false.

Fix: Set COOLIFY_ALLOW_STOP=true if stop operations are required.

Application logs truncated

Symptom: Logs show fewer lines than requested

Cause: Server caps at COOLIFY_LOG_MAX_LINES (default 200, max 1000).

Fix: Increase COOLIFY_LOG_MAX_LINES up to 1000, or request fewer lines.

Development

Commands

npm run dev          # Run in development mode with hot-reload (tsx watch)
npm run build        # Build to dist/ (tsup, ESM format)
npm start            # Run the built server
npm test             # Run all tests (vitest)
npm run test:watch   # Run tests in watch mode
npm run test:coverage # Run tests with coverage report
npm run lint         # Lint source code
npm run lint:fix     # Fix lint issues
npm run format       # Format with Prettier
npm run typecheck    # Type-check without emitting (tsc --noEmit)

Project Structure

src/
├── config/
│   ├── schema.ts              # Zod schema for all environment config
│   └── load-config.ts         # Config loading and validation
├── coolify/
│   ├── client.ts              # Coolify API HTTP client
│   ├── types.ts               # TypeScript types for Coolify data models
│   ├── normalizers.ts         # Response normalizers (strip undefined, redact secrets)
│   └── errors.ts              # Error handling and mapping
├── security/
│   ├── policy.ts              # Operation mode enforcement
│   ├── scope.ts               # Allowlist-based scope checking
│   ├── production-guard.ts    # Production environment protection
│   └── redaction.ts           # Secret redaction utilities
├── observability/
│   ├── logger.ts              # Pino logger with secret redaction
│   └── audit.ts               # Structured audit event logging
├── server/
│   └── create-server.ts       # MCP server setup and tool registration (42 tools)
├── tools/
│   ├── read/                  # 10 core read-only tools (Phase 1)
│   ├── actions/               # 11 action tools (5 Phase 1 + 6 Phase 2)
│   ├── discovery/             # 3 GitHub discovery tools (Phase 2)
│   ├── scheduled-tasks/       # 4 scheduled task tools (Phase 2)
│   ├── deployments/           # 1 deployment cancel tool (Phase 2)
│   ├── backups/               # 2 database backup tools (Phase 2)
│   ├── servers/               # 5 server tools (Phase 2)
│   ├── teams/                 # 2 team tools (Phase 2)
│   ├── configuration/         # 2 config update tools (Phase 2)
│   └── storage/               # 2 storage tools (Phase 2)
├── transports/
│   ├── stdio.ts               # stdio transport (default)
│   └── http.ts                # HTTP/SSE transport with auth
└── index.ts                   # Entry point

License

MIT

Install Server
A
license - permissive license
A
quality
C
maintenance

How are these scores calculated?

Maintenance

–Maintainers
–Response time
–Release cycle
–Releases (12mo)
Commit activity

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Tools

View all tools

Related MCP Servers

View all related MCP servers

Related MCP Connectors

  • microservices.sh

    MCP server for AI agents to plan, verify, and deploy Cloudflare-native apps.

  • Arcjet

    An MCP server for Arcjet - the runtime security platform that ships with your AI code.

  • Motecloud Memory

    Cloud-hosted MCP server for durable AI memory

View all MCP Connectors

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/hecateq/mcp-coolify'

If you have feedback or need assistance with the MCP directory API, please join our Discord server