StuMason/coolify-mcp

Coolify MCP Server

The most comprehensive MCP server for Coolify - 34 optimized tools, smart diagnostics, and batch operations for managing your self-hosted PaaS through AI assistants.

A Model Context Protocol (MCP) server for Coolify, enabling AI assistants to manage and debug your Coolify instances through natural language.

Features

This MCP server provides 34 token-optimized tools for debugging, management, and deployment:

v2.0.0 Token Diet

v2.0.0 reduced token usage by 85% (from ~43,000 to ~6,600 tokens) by consolidating related operations into single tools with action parameters. This prevents context window exhaustion in AI assistants.

Installation

Prerequisites

• Node.js >= 18
• A running Coolify instance
• Coolify API access token (generate in Coolify Settings > API)

Claude Desktop

Add to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

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

Claude Code

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

Note: Use @latest tag (not -y flag) for reliable startup in Claude Code CLI.

Cursor

env COOLIFY_ACCESS_TOKEN=your-api-token COOLIFY_BASE_URL=https://your-coolify-instance.com npx -y @masonator/coolify-mcp

Context-Optimized Responses

Why This Matters

The Coolify API returns extremely verbose responses - a single application can contain 91 fields including embedded 3KB server objects and 47KB docker-compose files. When listing 20+ applications, responses can exceed 200KB, which quickly exhausts the context window of AI assistants like Claude Desktop.

This MCP server solves this by returning optimized summaries by default.

How It Works

Response Size Comparison

Recommended Workflow

1. Start with overview: get_infrastructure_overview - see everything at once
2. Find your target: list_applications - get UUIDs of what you need
3. Dive deep: get_application(uuid) - full details for one resource
4. Take action: restart_application(uuid), get_application_logs(uuid), etc.

Pagination

All list endpoints still support optional pagination for very large deployments:

# Get page 2 with 10 items per page
list_applications(page=2, per_page=10)

Example Prompts

Getting Started

Give me an overview of my infrastructure
Show me all my applications
What's running on my servers?

Debugging & Monitoring

Diagnose my stuartmason.co.uk app
What's wrong with my-api application?
Check the status of server 192.168.1.100
Find any issues in my infrastructure
Get the logs for application {uuid}
What environment variables are set for application {uuid}?
Show me recent deployments for application {uuid}
What resources are running on server {uuid}?

Application Management

Restart application {uuid}
Stop the database {uuid}
Start service {uuid}
Deploy application {uuid} with force rebuild
Update the DATABASE_URL env var for application {uuid}

Project Setup

Create a new project called "my-app"
Create a staging environment in project {uuid}
Deploy my app from private GitHub repo org/repo on branch main

Environment Variables

Development

# Clone and install
git clone https://github.com/stumason/coolify-mcp.git
cd coolify-mcp
npm install

# Build
npm run build

# Test
npm test

# Run locally
COOLIFY_BASE_URL="https://your-coolify.com" \
COOLIFY_ACCESS_TOKEN="your-token" \
node dist/index.js

Available Tools

Infrastructure

• get_version - Get Coolify API version
• get_mcp_version - Get coolify-mcp server version (useful to verify which version is installed)
• get_infrastructure_overview - Get a high-level overview of all infrastructure (servers, projects, applications, databases, services)

Diagnostics (Smart Lookup)

These tools accept human-friendly identifiers instead of just UUIDs:

• diagnose_app - Get comprehensive app diagnostics (status, logs, env vars, deployments). Accepts UUID, name, or domain (e.g., "stuartmason.co.uk" or "my-app")
• diagnose_server - Get server diagnostics (status, resources, domains, validation). Accepts UUID, name, or IP address (e.g., "coolify-apps" or "192.168.1.100")
• find_issues - Scan entire infrastructure for unhealthy apps, databases, services, and unreachable servers

Servers

• list_servers - List all servers (returns summary)
• get_server - Get server details
• get_server_resources - Get resources running on a server
• get_server_domains - Get domains configured on a server
• validate_server - Validate server connection

Projects

• list_projects - List all projects (returns summary)
• get_project - Get project details
• create_project - Create a new project
• update_project - Update a project
• delete_project - Delete a project

Environments

• list_environments - List environments in a project
• get_environment - Get environment details
• create_environment - Create environment in a project
• delete_environment - Delete an environment

Applications

• list_applications - List all applications (returns summary)
• get_application - Get application details
• create_application_private_gh - Create app from private GitHub repo (GitHub App)
• create_application_private_key - Create app from private repo using deploy key
• update_application - Update an application
• delete_application - Delete an application
• start_application - Start an application
• stop_application - Stop an application
• restart_application - Restart an application
• get_application_logs - Get application logs
• list_application_envs - List application environment variables
• create_application_env - Create application environment variable
• update_application_env - Update application environment variable
• delete_application_env - Delete application environment variable

Databases

• list_databases - List all databases (returns summary)
• get_database - Get database details
• start_database - Start a database
• stop_database - Stop a database
• restart_database - Restart a database
• delete_database - Delete a database (with optional volume cleanup)
• list_database_backups - List scheduled backups for a database
• get_database_backup - Get details of a scheduled backup
• list_backup_executions - List execution history for a scheduled backup
• get_backup_execution - Get details of a specific backup execution

Services

• list_services - List all services (returns summary)
• get_service - Get service details
• create_service - Create a one-click service (e.g., pocketbase, mysql, redis, wordpress)
• update_service - Update a service
• delete_service - Delete a service
• start_service - Start a service
• stop_service - Stop a service
• restart_service - Restart a service
• list_service_envs - List service environment variables
• create_service_env - Create service environment variable
• delete_service_env - Delete service environment variable

Deployments

• list_deployments - List running deployments (returns summary)
• get_deployment - Get deployment details
• deploy - Deploy by tag or UUID
• cancel_deployment - Cancel a running deployment
• list_application_deployments - List deployments for an application

Private Keys

• list_private_keys - List all private keys (SSH keys for deployments)
• get_private_key - Get private key details
• create_private_key - Create a new private key for deployments
• update_private_key - Update a private key
• delete_private_key - Delete a private key

Batch Operations

Power user tools for operating on multiple resources at once:

• restart_project_apps - Restart all applications in a project
• bulk_env_update - Update or create an environment variable across multiple applications (upsert behavior)
• stop_all_apps - Emergency stop all running applications (requires confirmation)
• redeploy_project - Redeploy all applications in a project with force rebuild

Why Coolify MCP?

• Context-Optimized: Responses are 90-99% smaller than raw API, preventing context window exhaustion
• Smart Lookup: Find apps by domain (stuartmason.co.uk), servers by IP, not just UUIDs
• Batch Operations: Restart entire projects, bulk update env vars, emergency stop all apps
• Workflow Prompts: Pre-built guided workflows for common tasks
• Production Ready: 98%+ test coverage, TypeScript strict mode, comprehensive error handling
• Always Current: Weekly OpenAPI drift detection ensures we stay in sync with Coolify

Related Links

• Coolify - The open-source & self-hostable Heroku/Netlify/Vercel alternative
• Model Context Protocol - The protocol powering AI tool integrations
• MCP Server Registry - Official MCP server directory

Contributing

Contributions welcome! Please see for guidelines.

License

MIT - see for details.

Support

• GitHub Issues
• Coolify Community

If you find this useful, please ⭐ star the repo!