Coolify -for-Claude-Code

This MCP server provides a programmable interface to manage a Coolify instance via the Claude Code ecosystem. It exposes a suite of tools that cover core Coolify REST API endpoints, including applications, services, deployments, teams, domains, keys, and environment variables. You can query info, start/stop/restart applications and services, manage deployments and SSH keys, and CRUD environment variables across apps and services. The server is designed to be used from Claude Code (and Cursor) by generating an MCP command (claude mcp add) that includes the necessary environment variables so Claude can reliably launch and communicate with the server.

Once connected, you can issue natural-language prompts like "+List my applications+" or "+Show domains for server <uuid>+" to retrieve data or perform actions. The available tools are grouped into categories (System, Teams, Servers & Domains, Applications, Services, Deployments & Keys, and Environment Variables) and map directly to Coolify API endpoints. This makes it easy to perform day-to-day administration from Claude without manually crafting REST requests.

Prerequisites:

• Node.js v18 or newer
• npm or yarn
• Access to a running Coolify instance and a token with appropriate permissions

Step-by-step installation:

# 1) Clone the repository
git clone https://github.com/forsonny/Coolify-MCP-Server-for-Claude-Code.git
cd Coolify-MCP-Server-for-Claude-Code

# 2) Install dependencies
npm install

# 3) Build the project (compiles TypeScript into dist/)
npm run build

# 4) Create an environment file (example)
# COOlIFY_BASE_URL=https://your-coolify-instance.com
# COOLIFY_API_TOKEN=your-api-token-here
# COOLIFY_TIMEOUT=30000

# 5) Run the server locally (example)
npm run start

If you use Claude Code integration, you will generate an MCP command (via setup script or manual methods) that launches node dist/index.js with the required environment variables.

Environment variables:

• COOLIFY_BASE_URL: full base URL of your Coolify instance (no trailing slash)
• COOLIFY_API_TOKEN: token with permissions to manage resources
• COOLIFY_TIMEOUT: optional request timeout in milliseconds (default 30000)

Common issues:

• Ensure the .env values are loaded when Claude launches the MCP server. Explicit environment variable passing (Method 1 in Claude setup) is more reliable than relying on .env.
• If you modify the server code, re-build before re-connecting with Claude.
• Use a stable Coolify URL; avoid using localhost URLs unless your deployment topology requires it.

Configuration tips:

• The MCP server exposes tools that mirror Coolify API categories. You can extend or customize endpoints by editing src files and rebuilding.