forsonny/Coolify-MCP-Server-for-Claude-Code

Coolify MCP Server

A Model Context Protocol (MCP) server that integrates with Coolify to let AI assistants manage your Coolify instance via a clean toolkit that wraps the official REST API.

Table of Contents

• Features

• Prerequisites

• Installation

• Configuration

  • Environment Setup
  • Claude Code Setup
  • Cursor Setup

• API Token Generation

• Available Tools

• Usage Examples

• Development

• API Reference

• Troubleshooting

• Security

• Contributing

• License

• Support

Features

Core Capabilities

• Coverage of key Coolify API endpoints (applications, services, deployments, teams, private keys, domains, health/version)
• Team Management – List teams, get team details, and view members
• Server & Domain Insights – Query domains configured per server
• Application Lifecycle – Start/stop/restart and create applications
• Service Management – List/create/start/stop/restart services
• Deployments – List running deployments; fetch deployment by UUID
• Private Keys – List and create SSH private keys for server auth
• Env Vars – CRUD for application/service environment variables

Note: Some aggregated operations (e.g., "resources by server") are implemented by client-side filtering over the supported endpoints rather than a dedicated API path.

Prerequisites

• Node.js v18 or newer
• npm or yarn
• A running Coolify instance (self‑hosted or cloud)
• A Coolify API token with appropriate permissions

Installation

1) Clone & install

git clone https://github.com/forsonny/Coolify-MCP-Server-for-Claude-Code.git
cd Coolify-MCP-Server-for-Claude-Code
npm install

2) Build

npm run build

(Compiles TypeScript into dist/)

Configuration

Environment Setup

Create a .env file at the project root:

# Required
COOLIFY_BASE_URL=https://your-coolify-instance.com
COOLIFY_API_TOKEN=your-api-token-here

# Optional
COOLIFY_TIMEOUT=30000

Notes

• Use a full base URL (no trailing slash). Example: https://coolify.example.com
• Do not use inline comments in .env values.
• Never commit .env to version control.

Claude Code Setup

You can connect the server to Claude Code using the automated setup script or manually.

Option A — Automated Setup (Recommended)

The easiest way is to use the setup script:

# Run the setup script
npm run setup

This will:

• Validate your .env file configuration
• Build the TypeScript project if needed
• Generate the correct claude mcp add-json command with environment variables
• Provide troubleshooting tips

Option B — Manual Setup

If you prefer to set it up manually, you have two approaches:

Method 1: With explicit environment variables (most reliable)

claude mcp add-json coolify '{
  "type": "stdio",
  "command": "node", 
  "args": ["/absolute/path/to/Coolify-MCP-Server-for-Claude-Code/dist/index.js"],
  "env": {
    "COOLIFY_BASE_URL": "https://your-coolify-instance.com",
    "COOLIFY_API_TOKEN": "your-api-token-here",
    "COOLIFY_TIMEOUT": "30000"
  }
}' -s local

Method 2: Simple command (relies on .env file)

claude mcp add coolify "node /absolute/path/to/Coolify-MCP-Server-for-Claude-Code/dist/index.js" -s local

Verify the connection

claude mcp list

Option C — Import from Claude Desktop If you already have the server configured in Claude Desktop:

claude mcp add-from-claude-desktop
claude mcp list

Important: Method 1 (explicit environment variables) is more reliable because it ensures environment variables are available to the MCP server process, regardless of the working directory from which Claude Code launches the server.

Tip: Some setups store Claude Code MCP config in ~/.claude.json. The Desktop app uses claude_desktop_config.json under your OS application data directory.

Cursor Setup

Cursor supports MCP. The easiest route is through Settings → Extensions → MCP Servers → Add Server, then point to your built script (node …/dist/index.js) and add the three environment variables. Restart Cursor after saving.

For advanced/enterprise setups, see Cursor's MCP docs on programmatic registration.

API Token Generation

1. Open your Coolify dashboard.
2. Navigate to Keys & Tokens → API tokens.
3. Create a new token (name it e.g. "MCP Server"), select the permissions you need, and optionally set an expiration.
4. Copy the token once when shown and paste it into your .env.

Available Tools

System

Teams

Servers & Domains

Applications

Services

Deployments & Keys

Environment Variables

Application and service env vars support: list, create, update (single/bulk), and delete.

Usage Examples

Natural language you can try once connected:

Basics

"List my applications"
"Who's in the current team?"
"What version is my Coolify instance?"

Servers & Apps

"Show domains for server 123e4567-e89b-12d3-a456-426614174000"
"Create a new app from https://github.com/user/repo"
"Restart the backend app"

Services & Env Vars

"List running services"
"Create a PostgreSQL service on the main server"
"Add DATABASE_URL to the frontend app"

Development

Dev mode (watch):

npm run dev

Build:

npm run build

Setup:

npm run setup

Clean:

npm run clean

Project Structure

Coolify-MCP-Server-for-Claude-Code/
├── src/
│   ├── index.ts           # MCP server entrypoint
│   ├── coolify-client.ts  # Coolify API client
│   └── types.ts           # Type definitions
├── dist/                  # Compiled JS (generated)
├── .env                   # Environment variables (create this)
├── setup-mcp.js           # Setup script for easy configuration
├── package.json
├── tsconfig.json
└── README.md              # This file

API Reference

Selected endpoint mapping used by this server

Endpoint paths follow the official Coolify API and do not use a /api/v1 prefix.

Environment variable flags

Services are prebuilt images (no build phase), so is_build_time has no effect for services.

Troubleshooting

Server won't start

• Confirm Node ≥ 18: node --version
• Reinstall deps: rm -rf node_modules && npm install
• Rebuild: npm run clean && npm run build
• Confirm absolute paths in MCP config

Auth errors (401 Unauthorized)

• Verify token is valid and scoped to the correct team
• Recreate token if expired; paste into .env

Connection issues (ECONNREFUSED/timeouts)

• Check COOLIFY_BASE_URL (no trailing slash)
• Ensure the Coolify instance is reachable and healthy
• Increase COOLIFY_TIMEOUT for slow links

Tools not appearing

• Restart your client (Claude Code / Cursor)
• Verify with claude mcp list
• Check server logs in your terminal
• Ensure environment variables are set for the MCP process

Environment variable issues

If you see COOLIFY_BASE_URL and COOLIFY_API_TOKEN environment variables are required errors:

1. Use the automated setup script:

   npm run setup
   

2. Or use explicit environment variables: Remove the existing MCP server and re-add with explicit env vars:

   claude mcp remove coolify -s local
   claude mcp add-json coolify '{
     "type": "stdio",
     "command": "node",
     "args": ["/absolute/path/to/your/dist/index.js"],
     "env": {
       "COOLIFY_BASE_URL": "https://your-coolify-instance.com",
       "COOLIFY_API_TOKEN": "your-api-token-here"
     }
   }' -s local
   

3. Verify your .env file exists and has proper values:

   cat .env
   

Why this happens: When MCP servers are launched by Claude Code, they may run from a different working directory, causing the .env file to not be found. Explicit environment variables in the MCP configuration solve this issue.

Debug mode

DEBUG=coolify-mcp npm run dev

Security

• Keep API tokens out of VCS; rotate regularly
• Use HTTPS; consider IP allowlists / VPN for private instances
• Add .env to .gitignore; restrict file permissions
• Use least-privilege tokens per environment; audit and revoke regularly

Contributing

We welcome contributions!

1. Fork the repo and clone your fork

   git clone https://github.com/<your-username>/Coolify-MCP-Server-for-Claude-Code.git
   

2. Create a branch

   git checkout -b feat/your-feature
   

3. Code & test – follow existing style; add tests where useful

4. Commit

   git commit -m "feat: add <thing>"
   

5. Push & open PR

   git push origin feat/your-feature
   

Guidelines

• TypeScript best practices; backward compat where feasible
• Clear commit messages and error handling
• Update README when adding features

License

MIT — see .

Support

Issues – open on GitHub

Docs

• Coolify API Reference
• MCP SDK Documentation
• Claude Code Documentation
• Cursor MCP Guide

Version: 1.0.0 Maintainer: @forsonny