coolify-mcp

MCP server for Coolify API.

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 update

Requirements

• Node 18+
• A Coolify API token

Install

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

Registry Listings

• MCP Registry (API): https://registry.modelcontextprotocol.io/v0.1/servers/io.github.frndchagas%2Fcoolify-mcp/versions/0.1.4
• MCP Registry Docs: https://registry.modelcontextprotocol.io/docs

Use with Claude Code CLI

claude mcp add coolify \
  --env COOLIFY_BASE_URL="https://coolify.example.com" \
  --env COOLIFY_TOKEN="<token>" \
  -- npx -y @fndchagas/coolify-mcp

Disable write tools (deploy/env mutations):

--env COOLIFY_ALLOW_WRITE=false

Use with OpenAI Codex CLI

codex mcp add coolify \
  --env COOLIFY_BASE_URL="https://coolify.example.com" \
  --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", COOLIFY_TOKEN = "<token>" }

Development

npm install
npm run dev

Scripts

npm run dev            # Run in development mode
npm run build          # Build TypeScript
npm run generate       # Regenerate types from OpenAPI
npm run fetch:openapi  # Fetch latest OpenAPI spec
npm run update         # Fetch + regenerate

Environment Variables

Variable	Default	Description
COOLIFY_BASE_URL	required	Coolify API URL
COOLIFY_TOKEN	required	API token
COOLIFY_STRICT_VERSION	false	Fail on version mismatch
COOLIFY_ALLOW_WRITE	true	Enable write operations
COOLIFY_ALLOW_UNSAFE_LOGS	false	Allow raw logs without redaction
MCP_TRANSPORT	stdio	Transport: stdio, http, both
PORT	7331	HTTP port

Tools

Tools are exposed under your MCP server name. Example: if you register the server as coolify, the full tool name is coolify.listResources.

• listResources (args: limit, offset, summary, type, status)
• listApplications (args: limit, offset, summary - defaults to true)
• getApplication (args: uuid, fields, showSecrets)
• getLogs (args: uuid, lines, logMode)
• listEnvs (args: uuid, showSecrets - secrets masked by default)
• createEnv
• upsertEnv
• updateEnv
• deploy
• getDeployment (args: uuid, includeLogs, logMode)
• listDeployments (args: limit, offset, includeLogs, logMode)
• listAppDeployments (args: uuid, skip, take, includeLogs, logMode)
• listDatabases (args: limit, offset, type, showSecrets, summary - defaults to true)
• getDatabase (args: uuid, showSecrets)

Notes:

• listResources/listDatabases return a meta object with pagination info when limit or offset is provided.
• listEnvs masks sensitive values by default. Use showSecrets: true only when necessary.
• getApplication masks sensitive values by default. Use showSecrets: true only when necessary.
• listDeployments/listAppDeployments omit inline logs by default. Use includeLogs: true to include them (logs are redacted line-by-line, best-effort).
• logMode controls log sanitization: safe (default), strict (more aggressive), raw (requires COOLIFY_ALLOW_UNSAFE_LOGS=true).
• upsertEnv updates by key; if the key exists for both preview and non-preview, pass is_preview to disambiguate.
• upsertEnv defaults is_preview to false when omitted.
• Delete env is not available via this MCP (Coolify API does not expose it in the OpenAPI spec used here).

MCP Usage 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);

const resources = await client.callTool({
  name: 'coolify.listResources',
  arguments: {},
});
console.log(resources.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: 'node',
  args: ['dist/server.js'],
});

await client.connect(transport);

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

await client.close();