StuMason/coolify-mcp: MCP server for Coolify — 42 optimized tools for managing self-hosted PaaS through AI assistants

MCP server for Coolify — 42 optimized tools for managing self-hosted PaaS through AI assistants - StuMason/coolify-mcp

Summary

Coolify MCP Server is a TypeScript-based Model Context Protocol (MCP) server that exposes 46 tools for managing a self-hosted Coolify PaaS from AI assistants such as Claude or Cursor. It targets Coolify v4.0 through v4.3 and emphasizes safety: destructive operations pause for human confirmation, and secrets are masked at the API boundary. The project also ships an eval suite that red-teams model-driven flows on every change.

What it is useful for

This server is built for engineers running Coolify who would rather operate their infrastructure through plain English than click through dashboards or hand-roll curl scripts. Documented workflows cover diagnosing misbehaving apps via diagnose_app (which accepts a name, domain, IP or UUID), pulling container logs with logs, and scanning an estate with find_issues. It also handles deploys with deploy, which waits for a terminal status and returns the log tail on failure, plus bulk env-var updates, project redeploys, and creating or destroying applications and databases across eight engines.

For teams running more than one Coolify instance, fleet mode lets every tool accept an optional instance parameter and adds a list_instances reporter. Three prompt workflows ship as slash commands (troubleshoot_application, explain_failed_deploy, estate_health) that walk a model through a sequence using the tools it already has, plus a search_docs tool for Coolify's own documentation.

How engineers can use it

The README lists three installation paths. The simplest is downloading coolify-mcp.mcpb and dragging it into Claude Desktop's Extensions settings, where you are prompted for the Coolify URL and token.

For other clients, the local path uses npx:

claude mcp add coolify \
  -e COOLIFY_BASE_URL="https://your-coolify-instance.com" \
  -e COOLIFY_ACCESS_TOKEN="your-api-token" \
  -- npx @masonator/coolify-mcp@latest

The same npx invocation works inside a JSON config block for Cursor, Claude Desktop, or any stdio-only client, with COOLIFY_BASE_URL and COOLIFY_ACCESS_TOKEN as environment variables.

After configuring, run npx @masonator/coolify-mcp doctor with the same env vars. It validates that the token is accepted, Coolify is reachable, your version is supported, and flags common misconfigurations like doubled /api/v1 paths or Cloudflare Access login walls. For HTTP-only clients, the server can also be deployed as a container inside Coolify itself with OAuth 2.1 client authentication, documented in docs/http-mode.md.

Documented limitations: human-in-the-loop confirmation for destructive operations requires a client that supports MCP elicitation (Claude Code and VS Code Copilot are mentioned). In HTTP mode, elicitation is unavailable and the guard fails closed. The server only supports Coolify v4.0–v4.3, and tokens must be created in Coolify's Keys & Tokens panel.