🚀 Coolify MCP Server (coolify-mcp)

🚀 Coolify MCP Server (coolify-mcp)

A comprehensive, production-grade Model Context Protocol (MCP) server for Coolify v4 self-hosted PaaS.

Connect AI coding assistants and agents (Claude Desktop, Cursor, Antigravity, Claude Code, Windsurf, Cline, and VS Code) directly to your Coolify instance to orchestrate infrastructure, deploy applications, manage 8 types of databases, handle environment variables, and diagnose logs using natural language.

🌟 Why coolify-mcp?

• 🌐 100% Full Coolify v4 API Coverage: 77 verified MCP tools covering Projects, Environments, Servers, Applications, Databases, Docker Compose Services, Deployments, Team Members, and SSH Keys.
• 🔒 Read-Only Safety Guard: Enable --read-only (or COOLIFY_READ_ONLY=true) to let AI assistants audit, monitor, and troubleshoot without any mutating or destructive actions.
• 🗄️ Universal Database Engine Support: Out-of-the-box creation and configuration for PostgreSQL, MySQL, MariaDB, MongoDB, Redis, ClickHouse, Dragonfly, and KeyDB with engine-specific parameter normalization.
• 📊 Dynamic MCP Resources: Native resources (coolify://overview, coolify://servers, coolify://applications, coolify://databases) for zero-token ambient context.
• 💡 DevOps Prompt Templates: Pre-built prompt recipes (diagnose-application, infrastructure-audit, deployment-summary) for autonomous diagnostics and health checks.
• 🐳 Docker & Stdio Transport Ready: Run as a standard Node CLI tool or inside isolated Docker containers with container-to-container network support.

🤖 AI Agent Setup Prompt (Copy & Paste)

If you are using an AI coding assistant (like Antigravity, Claude Code, Cursor, Windsurf, or Cline), simply copy and paste the prompt below into your assistant:

Please configure and set up the Coolify MCP server for me from https://github.com/frizikk/coolify-mcp.git.

Follow these steps:
1. Clone the repository:
   git clone https://github.com/frizikk/coolify-mcp.git
2. Install dependencies and build the server:
   cd coolify-mcp && pnpm install && pnpm build
3. Guide me to provide my Coolify instance URL (e.g. https://coolify.my-domain.com or http://localhost:8000) and API Bearer Token (generated in Coolify under Keys & Tokens / Settings -> API).
4. Add the `coolify` server configuration to my MCP client config (e.g., in Claude Desktop `claude_desktop_config.json`, Cursor `~/.cursor/mcp.json`, or Antigravity `~/.gemini/config/mcp_config.json`).
5. Test the connection by calling `coolify_get_version` and `coolify_get_infrastructure_overview` to verify connection to my Coolify instance.

🛠️ MCP Tools Reference

The server exposes 77 specialized tools organized across 8 core DevOps domains:

1. System & Infrastructure Overview (4 tools)

2. Servers & Nodes Management (8 tools)

3. Teams & SSH Keys (9 tools)

4. Projects & Environments (9 tools)

5. Applications (16 tools)

6. Deployments (5 tools)

7. Databases (14 tools)

8. One-Click Services & Docker Compose (12 tools)

📊 MCP Resources & Prompts

Resources

• coolify://overview — Aggregated real-time summary of all servers, apps, databases, and services.
• coolify://servers — Live list of servers and reachability status.
• coolify://applications — Live status of all applications and URLs.
• coolify://databases — Live status of database containers.

Prompts

• diagnose-application — Automated diagnostic workflow: checks application state, analyzes recent logs, and inspects environment variables.
• infrastructure-audit — Complete infrastructure health check across servers, disk limits, and failed containers.
• deployment-summary — Analyzes recent deployments and surfaces build failures.

⚙️ Configuration & Client Setup

Environment Variables

Client Config Examples

1. Claude Desktop

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "coolify": {
      "command": "node",
      "args": ["/path/to/coolify-mcp/dist/index.js"],
      "env": {
        "COOLIFY_BASE_URL": "https://coolify.yourdomain.com",
        "COOLIFY_API_TOKEN": "your-bearer-token"
      }
    }
  }
}

2. Cursor (~/.cursor/mcp.json or project .cursor/mcp.json)

{
  "mcpServers": {
    "coolify": {
      "command": "node",
      "args": ["/path/to/coolify-mcp/dist/index.js"],
      "env": {
        "COOLIFY_BASE_URL": "https://coolify.yourdomain.com",
        "COOLIFY_API_TOKEN": "your-bearer-token"
      }
    }
  }
}

3. Antigravity (~/.gemini/config/mcp_config.json)

{
  "mcpServers": {
    "coolify": {
      "command": "node",
      "args": ["/path/to/coolify-mcp/dist/index.js"],
      "env": {
        "COOLIFY_BASE_URL": "https://coolify.yourdomain.com",
        "COOLIFY_API_TOKEN": "your-bearer-token"
      }
    }
  }
}

4. Docker Container Mode

docker run -i --rm \
  -e COOLIFY_BASE_URL="http://coolify:8080" \
  -e COOLIFY_API_TOKEN="your-bearer-token" \
  --network coolify-network \
  coolify-mcp:latest

🧪 Testing & Verification

The test suite includes unit tests and full end-to-end integration tests executed against a live Dockerized Coolify v4 instance:

# Run all automated unit and integration tests (43 tests)
pnpm test

# Run complete 77-tool live verification suite
pnpm test:verify-live

📄 License

Distributed under the MIT License. See LICENSE for details.