mcp-server-coolify

pavelsukhachev/mcp-server-coolify

3.3

If you are the rightful owner of mcp-server-coolify and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to henry@mcphub.com.

Coolify MCP Server is a comprehensive Model Context Protocol server designed for managing infrastructure, applications, databases, and services through the Coolify PaaS platform.

Tools

  1. coolify_version

    Get Coolify version information

  2. coolify_health

    Check Coolify API health status

  3. list_teams

    List all teams

  4. get_team

    Get details of a specific team

  5. list_servers

    List all servers

Coolify MCP Server

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:

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