Coolify MCP Server

<img src="graphics/CoolifyMCP.png" width="256" alt="Coolify MCP Logo" />

A comprehensive Model Context Protocol (MCP) server for the Coolify API. This server enables AI assistants to manage infrastructure, applications, databases, services, and more through your self-hosted Coolify PaaS platform.

Compatibility: Tested with Coolify version 4.0.0-beta.418

---

👋 Open for Opportunities!
I'm actively seeking new opportunities and collaborations. If you have interesting projects or job opportunities, feel free to reach out!
📧 Contact: pashvc@gmail.com

---

Prerequisites

• Node.js 18 or higher
• Coolify Base URL
• Coolify API token

Features

Core Management

• Teams: List teams, get team details, view team members
• Projects: Create, list, update, and delete projects
• Servers: Create servers, validate connections, view resources and domains
• Private Keys: Manage SSH keys for server access

Applications

• Full CRUD operations (create, read, update, delete)
• Lifecycle management (start, stop, restart)
• Execute commands in containers
• View application logs
• Git integration (repository, branch, commit management)
• Resource limits configuration (memory, CPU)
• Health check configuration

Databases

• Support for PostgreSQL, MySQL, MariaDB, MongoDB, and Redis
• Create and manage database instances
• Configure database-specific settings
• Lifecycle management (start, stop, restart)
• Resource limits and public port configuration

Services

• Deploy pre-configured services (Plausible, Umami, n8n, etc.)
• Service lifecycle management
• Configuration updates

Environment Variables

• Manage environment variables for applications, services, and databases
• Support for build-time and runtime variables
• Preview deployment variables
• Shared variables across environments

Deployments

• List all deployments
• Get deployment details and logs
• Trigger deployments via webhook
• Support for Docker image tags

Developer Experience

• Pre-configured prompts for common workflows
• Comprehensive error handling with detailed messages
• TypeScript support with full type safety
• Integration with MCP Inspector for debugging
• Robust API response handling for different Coolify versions
• Extensive test coverage with both unit and integration tests

Installation

# Install globally
npm install -g @pashvc/mcp-server-coolify

# Or use with npx
npx @pashvc/mcp-server-coolify

Configuration

The server requires two environment variables:

• COOLIFY_BASE_URL: The base URL of your Coolify instance
• COOLIFY_TOKEN: Your Coolify API token

Getting an API Token

1. Go to your Coolify instance
2. Navigate to Keys & Tokens / API tokens
3. Create a new token with the following required permissions:
   • read (for fetching information)
   • write (for managing resources)
   • deploy (for deployment operations)

Usage

In MCP Settings

Add the following to your MCP settings configuration:

{
  "mcpServers": {
    "coolify": {
      "command": "npx",
      "args": ["-y", "@pashvc/mcp-server-coolify"],
      "env": {
        "COOLIFY_BASE_URL": "your-coolify-url",
        "COOLIFY_TOKEN": "your-api-token"
      },
      "disabled": false,
      "autoApprove": []
    }
  }
}

Windows Cline users may need the following:

{
  "mcpServers": {
    "coolify": {
      "command": "cmd",
      "args": [
        "/c",
        "npx",
        "-y",
        "@pashvc/mcp-server-coolify"
      ],
      "env": {
        "COOLIFY_BASE_URL": "your-coolify-url",
        "COOLIFY_TOKEN": "your-api-token"
      },
      "disabled": false,
      "autoApprove": []
    }
  }
}

Available Tools

Version & Health

• coolify_version: Get Coolify version information
• coolify_health: Check Coolify API health status

Teams

• list_teams: List all teams
• get_team: Get details of a specific team
• get_current_team: Get current team details
• get_current_team_members: Get current team members

Servers

• list_servers: List all servers
• create_server: Create a new server
• validate_server: Validate server configuration
• get_server_resources: Get server resources
• get_server_domains: Get server domains

Projects

• list_projects: List all projects
• get_project: Get project details
• create_project: Create a new project
• update_project: Update project settings
• delete_project: Delete a project

Applications

• list_applications: List all applications
• get_application: Get application details
• create_application: Create a new application
• update_application: Update application settings
• delete_application: Delete an application
• start_application: Start an application
• stop_application: Stop an application
• restart_application: Restart an application
• execute_command: Execute command in application container
• get_application_logs: Get application logs

Databases

• list_databases: List all databases
• get_database: Get database details
• create_database: Create a new database
• update_database: Update database settings
• delete_database: Delete a database
• start_database: Start a database
• stop_database: Stop a database
• restart_database: Restart a database

Services

• list_services: List all services
• get_service: Get service details
• create_service: Create a new service
• update_service: Update service settings
• delete_service: Delete a service
• start_service: Start a service
• stop_service: Stop a service
• restart_service: Restart a service

Environment Variables

• list_environment_variables: List environment variables
• create_environment_variable: Create a new environment variable
• update_environment_variable: Update an environment variable
• delete_environment_variable: Delete an environment variable

Deployments

• list_deployments: List all deployments
• get_deployment: Get deployment details
• deploy_webhook: Trigger deployment via webhook

Private Keys

• list_private_keys: List all private keys
• create_private_key: Create a new private key
• update_private_key: Update a private key
• delete_private_key: Delete a private key

Pre-configured Prompts

The server includes helpful prompts for common workflows:

• deploy-git-app: Deploy a new application from a Git repository
• setup-database: Set up a new database with proper configuration
• deploy-service: Deploy a pre-configured service
• environment-setup: Set up environment variables for an application
• server-health-check: Comprehensive health check of all servers
• backup-database: Create a backup of a database
• scale-application: Scale an application by adjusting resources
• setup-ssl: Configure SSL/TLS for an application
• migrate-application: Migrate an application between servers
• troubleshoot-deployment: Troubleshoot a failed deployment

Development

Building from Source

# Clone the repository
git clone https://github.com/pashvc/mcp-server-coolify.git
cd mcp-server-coolify

# Install dependencies
npm install

# Build the project
npm run build

# Run tests
npm test

Development Scripts

• npm run build: Build the TypeScript project
• npm run watch: Build and watch for changes
• npm test: Run all tests
• npm run test:watch: Run tests in watch mode
• npm run test:coverage: Run tests with coverage report
• npm run test:integration: Run integration tests only (requires env vars)
• npm run inspector: Launch MCP Inspector for debugging

Troubleshooting

Common Issues

• 404 Errors: Some endpoints may not be available in all Coolify versions. The server automatically handles different response formats across versions.
• Authentication Errors: Ensure your API token has the required permissions (read, write, deploy).
• Connection Issues: Verify your COOLIFY_BASE_URL is correct and accessible.
• Environment Variables: Make sure both COOLIFY_BASE_URL and COOLIFY_TOKEN are set correctly.

Testing Your Setup

# Test with your credentials
export COOLIFY_BASE_URL="https://your-coolify-instance.com"
export COOLIFY_TOKEN="your-api-token"

# Run integration tests to verify connectivity
npm run test:integration

# Or test the server directly
npm run build && npm start

API Compatibility

The server handles different response formats automatically:

• Version endpoint: Supports both string and object responses
• List endpoints: Handles both direct arrays and paginated responses
• Health endpoint: Adapts to different status response formats
• Error handling: Robust parsing of various error message formats

License

MIT