Summary

StuMason/coolify-mcp provides a Model Context Protocol (MCP) server designed to bridge AI assistants with self-hosted PaaS instances managed by Coolify. It addresses the challenge of AI context window limitations by offering 38 token-optimized tools that drastically reduce response verbosity. This enables AI assistants to efficiently manage, debug, and deploy applications on Coolify via natural language, benefiting power users and engineers seeking streamlined infrastructure control.

How It Works

The MCP server acts as an intelligent proxy, intercepting AI requests and translating them into optimized calls to the Coolify API. Its core innovation lies in consolidating multiple operations into single, parameterized tools and returning highly summarized data (e.g., UUIDs, names, statuses) instead of verbose raw API objects. This approach reduces response token counts by up to 99%, preventing AI context window exhaustion. Responses also include HATEOAS-style _actions and pagination links, guiding AI assistants on logical next steps and resource discovery.

Quick Start & Requirements

• Primary install/run command: npx -y @masonator/coolify-mcp (for direct execution) or npm install followed by node dist/index.js after cloning.
• Prerequisites: Node.js >= 18, a running Coolify instance (tested with v4.0.0-beta.460), and a Coolify API access token.
• Configuration: Requires COOLIFY_ACCESS_TOKEN and COOLIFY_BASE_URL environment variables. Specific setup instructions are provided for Claude Desktop and Cursor.
• Relevant links: Coolify MCP Registry, Coolify documentation.

Highlighted Details

• Context-Optimized Responses: Significantly reduces data transfer (90-99% reduction) compared to direct Coolify API calls, crucial for AI assistant context limits.
• Smart Lookup: Tools accept human-friendly identifiers (names, domains, IPs) for resources, not just UUIDs.
• HATEOAS-style Actions: Responses include contextual _actions suggesting relevant next steps for AI assistants.
• Batch Operations: Provides tools for managing multiple resources simultaneously, such as restarting all apps in a project or performing bulk environment variable updates.
• Integrated Documentation Search: Offers full-text search across Coolify's documentation, allowing AI assistants to find relevant information contextually.

Maintenance & Community

This project is developed and maintained by Stu Mason. Support is primarily handled through GitHub Issues. No dedicated community channels like Discord or Slack are explicitly mentioned in the README.

Licensing & Compatibility

The project is released under the MIT License, which permits commercial use and integration into closed-source projects.

Limitations & Caveats

The README notes testing with a specific beta version of Coolify (v4.0.0-beta.460), suggesting potential compatibility nuances with other Coolify versions. The documentation search feature indexes documentation on its first call, which may introduce a minor delay during initial use.