Coolify MCP Server: Seamless Integration for AI Applications

Overview: What is Coolify MCP Server?

Coolify MCP Server is an implementation of the Model Context Protocol (MCP) designed to enable AI assistants and applications to interact with Coolify instances through natural language commands. This server acts as a bridge, translating human-written prompts into actionable requests to manage servers, projects, databases, services, deployments, and more on your Coolify instance.

🔧 Core Features & MCP Capabilities

Enhanced AI Application Ecosystem

Coolify MCP Server supports cutting-edge AI applications such as Claude Desktop, Continue, and Cursor, providing a seamless bridge between these powerful tools and the diverse functionalities of Coolify. The server enhances the capabilities of these applications by allowing them to issue complex commands in plain English, directly influencing server configurations, project management, database operations, and deployment processes.

Comprehensive Command Set

The server supports a wide range of commands categorized into several key areas:

• Server Management: Commands like listing, inspecting, validating, monitoring, and managing resources for servers.
• Project Management: Operations such as listing, creating, updating, deleting projects, and managing environments.
• Application & Service Management: Tasks including creating, updating, deploying applications and services, and configuring their environment settings.
• Database Management: Capabilities to manage databases, including creation, configuration, and deletion.
• Deployment Management: Features for tracking deployment statuses, rebuilding, and listing recent deployments.

These commands are designed to give AI assistants the freedom to execute a broad spectrum of management tasks through natural language input.

Real-Time Data Interaction

MCP Server ensures real-time data interaction by constantly syncing with Coolify resources. This dynamic exchange enables AI applications to receive updated states and configurations, ensuring that commands are always executed based on the latest information available.

⚙️ MCP Architecture & Protocol Implementation

Architecture Overview

The architecture of Coolify MCP Server is designed around the Model Context Protocol (MCP), which serves as the basis for its communication with AI applications. The server consists of several key components:

• Protocol Adapters: These adapters handle the conversion between natural language commands and structured API requests to Coolify.
• AI Application Clients: Compatibility modules that interact with popular AI applications, ensuring seamless operation.
• Data Management Layer: A robust layer that stores and retrieves data related to servers, projects, databases, and services.

Protocol Flow Diagram

The following Mermaid diagram illustrates the protocol flow between an AI application, Coolify MCP Server, and Coolify resources:

graph TD
    A[AI Application] -->|MCP Client| B[MCP Protocol]
    B --> C[MCP Server]
    C --> D[Data Source/Tool]
    style A fill:#e1f5fe
    style B fill:#a2d6ff
    style C fill:#f3e5f5
    style D fill:#e8f5e8

Data Architecture Diagram

The data architecture diagram below illustrates how Coolify MCP Server manages and interacts with different types of data:

graph TB
    A[Applications] --> B[Services]
    B --> C[Databases]
    C --> D[Deployments]
    style A fill:#c6d5f4
    style B fill:#fbecba
    style C fill:#bfe8c3
    style D fill:#e1ecff

🚀 Getting Started with Installation

Prerequisites

To install and set up Coolify MCP Server, you will need:

• Node.js version 18 or higher.
• A running instance of Coolify.
• An API access token from your Coolify account.

Setup Instructions

Via JSON Configuration

Ensure your AI application is configured to use Coolify MCP Server, as shown below for Claude Desktop:

{
  "coolify": {
    "command": "npx",
    "args": [
      "-y", "@masonator/coolify-mcp"
    ],
    "env": {
      "COOLIFY_ACCESS_TOKEN": "0|your-secret-token",
      "COOLIFY_BASE_URL": "https://your-coolify-instance.com"
    }
  }
}

Via Command Line

You can also set up Coolify MCP Server via the command line using the following bash script:

env COOLIFY_ACCESS_TOKEN:0|your-secret-token COOLIFY_BASE_URL:https://your-coolify-instance.com npx -y @stumason/coolify-mcp

💡 Key Use Cases in AI Workflows

Real-World Workflow 1: Server and Resource Management

Imagine you are an IT manager who needs to quickly provision a new server, configure it with necessary resources, and deploy applications without leaving your AI assistant. Using Coolify MCP Server, you can issue commands like:

Show me all my Coolify servers in this instance.

Followed by more detailed tasks such as:

Create a new project called "my-webapp" in the production environment.
Deploy application {uuid} to server {uuid}.

Real-World Workflow 2: Database and Project Management

For database administrators, managing multiple databases can be complex. With Coolify MCP Server, you can simplify this process with commands like:

List all databases on my production project.
Update the configuration for database {uuid}:
    - Increase memory limit to 1GB
    - Change public port to 5432.

You can also manage projects and environments with commands such as:

Show me all servers in project {uuid}.
Validate the connection to server {uuid}.

🔌 Integration with MCP Clients

Coolify MCP Server supports multiple MCP clients, including Claude Desktop, Continue, and Cursor. Each client is compatible with the following features:

• Claude Desktop: Full support for applications, services, projects, and databases.
• Continue: Similar to Claude Desktop, with added real-time data feedback loops.
• Cursor: Support limited to tools but does not provide full AI application integration.

📊 Performance & Compatibility Matrix

MCP Client Compatibility

The following table summarizes the compatibility matrix for Coolify MCP Server:

MCP Client	Application	Service	Project Environment	Prompt
Claude Desktop	✅	✅	✅	✅
Continue	✅	✅	✅	✅
Cursor	❌	✅	❌	❌

🛠️ Advanced Configuration & Security

Environment Variables

Configuring Coolify MCP Server involves setting several environment variables to establish the connection. These include:

• COOLIFY_ACCESS_TOKEN: Required for authentication.
• COOLIFY_BASE_URL: Optional, defaults to http://localhost:3000.

For secure setups, consider implementing additional security measures such as HTTPS and using environment-specific tokens.

Advanced Authentication

To enhance security, you can use OAuth2 or custom tokens. This involves issuing tokens that are time-bound and scoped to specific actions, adding an extra layer of security to your setup.

❓ Frequently Asked Questions (FAQ)

Q1: How do I integrate Coolify MCP Server with my AI application?

You can integrate by configuring the server using JSON settings for popular clients like Claude Desktop or via command line settings for Cursor.

Q2: Can I use Coolify MCP Server with tools other than AI applications?

Currently, the primary focus is on AI applications. However, the protocol allows future extensions to support additional tools and services.

Q3: How do I troubleshoot issues if my prompts are not being executed correctly?

Check your environment variables for any missing or incorrect configuration. Additionally, review the server logs for any errors that might provide clues about what went wrong.

Q4: Can I use Coolify MCP Server with multiple instances of Coolify?

Yes, you can connect to multiple instances by setting different COOLIFY_BASE_URL and COOLIFY_ACCESS_TOKEN. Each instance will require separate configurations.

Q5: Is there a way to customize the response format from Coolify MCP Server?

The server responds using standard JSON formats. While customization is not directly available, you can script additional handling of responses within your AI application to fit specific needs.

👨‍💻 Development & Contribution Guidelines

Contributions are welcome and encouraged! To get started:

1. Fork the Repository: Clone or fork the source code from GitHub.
2. Set Up the Project: Follow the provided installation instructions in the README.
3. Run Tests: Ensure your changes pass all existing test cases.
4. Commit Your Changes: Write clear commit messages and ensure readability.
5. Open a Pull Request: Submit your request for review.

🌐 MCP Ecosystem & Resources

For more information on Model Context Protocol (MCP) and its ecosystem, visit the official MCP documentation. The community welcomes active participants who can contribute to the adoption and evolution of MCP.

---

This comprehensive guide positions Coolify MCP Server as a powerful tool for integrating AI applications with Coolify instances. By leveraging the Model Context Protocol, this server ensures seamless, efficient, and secure operations across a wide range of management tasks.