Coolify

coolify-mcp

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

Targets the Coolify v4.3.10 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 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:

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

Quick Start

Claude Code CLI

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

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:

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

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

Teams, Servers & Git

Tool	Description	Write
teams	List teams, get current team, and list members
updateServer	Update server configuration	✓
deleteServer	Delete a server	✓
getServerResources	List resources running on a server
getServerDomains	List domains configured on a server
getPrivateKey	Get SSH key metadata (key material masked by default)
updatePrivateKey	Update an SSH private key	✓
deletePrivateKey	Delete an SSH private key	✓
getGithubAppRepositories	List repositories accessible to a GitHub App
getGithubAppBranches	List branches of a repository

Batch Operations

Tool	Description	Write
getInfrastructureOverview	One-call summary of servers, projects, applications (status breakdown), databases, services, and running deployments
restartProjectApps	Restart every application in a project or environment (asks for confirmation)	✓
redeployProject	Trigger a deployment for every application in a project or environment (asks for confirmation)	✓
stopAllApplications	Emergency stop of all running applications, optionally per project (asks for confirmation, stating the blast radius)	✓

Other

Tool	Description
listResources	List all resources with filtering
searchDocs	Full-text search across the official Coolify docs (bundled index, no network)
getHealth	Check that the Coolify API is up

Security Features

Write Protection

Disable all write operations:

COOLIFY_ALLOW_WRITE=false

Secret Masking

• Environment variable values are masked by default
• Database credentials are redacted
• Use showSecrets: true only when necessary

HTTP Transport Hardening

The HTTP transport binds to 127.0.0.1 by default. To expose it beyond loopback, set MCP_HTTP_TOKEN — every request to /mcp must then carry Authorization: Bearer <token> (checked in constant time) — and the bind switches to 0.0.0.0 (override with MCP_HTTP_HOST). Binding to a non-loopback host without a token logs a loud warning: anyone who can reach the port controls your Coolify instance.

Human Confirmation on Destructive Deletes

On MCP clients that support elicitation (Claude Code, VS Code Copilot), deleting a project, application, database, service, server, or private key asks you to confirm first, stating what will be lost. Clients without elicitation behave exactly as before. A decline, cancel, or timeout aborts the call; set COOLIFY_MCP_ELICITATION=off to disable the prompts entirely.

Development

git clone https://github.com/frndchagas/coolify-mcp.git
cd coolify-mcp
npm install
npm run dev

Scripts

npm run dev            # Run in development mode
npm run build          # Build TypeScript
npm run generate       # Fetch the pinned OpenAPI spec and regenerate types

Pinned Coolify Version

Version is defined in src/coolify/constants.ts. To update:

1. Edit COOLIFY_VERSION in src/coolify/constants.ts
2. Run npm run generate

Registry Listings

• MCP Registry: io.github.frndchagas/coolify-mcp

MCP Client Examples

HTTP Client

import { Client } from '@modelcontextprotocol/sdk/client/index.js';
import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js';

const client = new Client({ name: 'coolify-client', version: '1.0.0' });
const transport = new StreamableHTTPClientTransport(
  new URL('http://localhost:7331/mcp')
);

await client.connect(transport);

// List all applications
const apps = await client.callTool({
  name: 'listApplications',
  arguments: {},
});
console.log(apps.structuredContent);

// Deploy an application
const deploy = await client.callTool({
  name: 'deploy',
  arguments: { uuid: 'your-app-uuid' },
});
console.log(deploy.structuredContent);

await client.close();

Stdio Client

import { Client } from '@modelcontextprotocol/sdk/client/index.js';
import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';

const client = new Client({ name: 'coolify-client', version: '1.0.0' });
const transport = new StdioClientTransport({
  command: 'npx',
  args: ['-y', '@fndchagas/coolify-mcp'],
  env: {
    COOLIFY_BASE_URL: 'https://coolify.example.com/api/v1',
    COOLIFY_TOKEN: '<token>',
  },
});

await client.connect(transport);

const result = await client.callTool({
  name: 'getApplication',
  arguments: { uuid: 'your-app-uuid' },
});
console.log(result.structuredContent);

await client.close();

License

MIT