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 | | 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
• listApplications
• getApplication
• getLogs
• listEnvs
• createEnv
• updateEnv
• deploy
• getDeployment
• listDatabases
• getDatabase

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();