🚀 Enhanced Coolify MCP Server

A powerful, enhanced Model Context Protocol (MCP) server for Coolify that enables AI assistants to manage your entire Coolify infrastructure through natural language. Deploy applications, manage databases, monitor services, and automate your DevOps workflows - all through simple conversations with AI.

✨ What Makes This Enhanced?

This is a significantly enhanced version of the original Coolify MCP Server with 15+ new tools and powerful automation capabilities:

🎯 New Capabilities

Complete Application Lifecycle Management - Create, deploy, monitor, and manage applications
Infrastructure Automation - One-click deployment of PostgreSQL, Redis, and MinIO stacks
Real-time Monitoring - Resource usage, logs, and deployment status tracking
Environment Management - Bulk environment variable updates and configuration
Docker Compose Support - Deploy custom Docker Compose services
Advanced Deployment Control - Monitor, cancel, and manage deployments

🛠️ Perfect For

Developers - Streamline your deployment workflows
DevOps Teams - Automate infrastructure management
Beginners - Easy setup with clear examples
AI Enthusiasts - Natural language infrastructure control

📋 Prerequisites

Before installation, ensure you have:

Node.js 18+ installed
Git installed
Access to a Coolify server (self-hosted, v0cl.one, or Coolify Cloud)
Coolify API token with appropriate permissions

🎬 Quick Start Guide

Option A: Interactive Setup (Recommended for Beginners)

# Clone and run the interactive setup guide
git clone https://github.com/dazeb/coolify-mcp-enhanced.git
cd coolify-mcp-enhanced
npm install && npm run build
node setup-guide.js

The interactive guide will walk you through:

✅ Getting your Coolify API token
✅ Configuring your server URL
✅ Setting up your AI assistant
✅ Testing the connection

Option B: Manual Setup

Step 1: Get Your Coolify API Token

Log into your Coolify dashboard (e.g., https://your-coolify-server.com)
Go to API Tokens (usually in Settings or Profile)
Create a new token with appropriate permissions
Copy the token - it looks like: 0|1234567890abcdef...

Step 2: Install the Enhanced MCP Server

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

# Install dependencies and build
npm install
npm run build

Step 3: Configure Your Environment

# Set your Coolify server details
export COOLIFY_ACCESS_TOKEN="0|your-actual-token-here"
export COOLIFY_BASE_URL="https://your-coolify-server.com"

# Example for common Coolify hosting services:
# export COOLIFY_BASE_URL="https://s1.v0cl.one"  # v0cl.one hosting
# export COOLIFY_BASE_URL="https://app.coolify.io"  # Coolify Cloud
# export COOLIFY_BASE_URL="https://coolify.yourdomain.com"  # Self-hosted

Step 4: Test the Connection

# Test basic functionality
node test-mcpaas.js

# You should see:
# ✅ GitHub Repo: PASS
# ✅ Basic connectivity working

Step 5: Quick Verification

# Test MCP server directly
echo '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"list_servers","arguments":{}}}' | node dist/index.js

# Expected output: JSON response with your Coolify server information

⚡ One-Command Installation

For AI agents or advanced users, here's the complete installation in one command:

git clone https://github.com/dazeb/coolify-mcp-enhanced.git && cd coolify-mcp-enhanced && npm install && npm run build && echo "✅ Installation complete! Run 'node setup-guide.js' for configuration."

🤖 AI Assistant Integration

Claude Desktop Setup

Add this to your claude_desktop_config.json:

{
  "mcpServers": {
    "coolify-enhanced": {
      "command": "node",
      "args": ["/full/path/to/coolify-mcp-enhanced/dist/index.js"],
      "env": {
        "COOLIFY_ACCESS_TOKEN": "0|your-actual-token-here",
        "COOLIFY_BASE_URL": "https://your-coolify-server.com"
      }
    }
  }
}

Kiro IDE Setup (Real Example)

Here's a real working example from a v0cl.one user:

{
  "mcpServers": {
    "coolify-enhanced": {
      "command": "node",
      "args": ["coolify-mcp-enhanced/dist/index.js"],
      "env": {
        "COOLIFY_ACCESS_TOKEN": "17|your-actual-token-here",
        "COOLIFY_BASE_URL": "https://s1.v0cl.one"
      },
      "disabled": false,
      "autoApprove": [
        "list_servers",
        "list_services", 
        "list_projects",
        "list_applications",
        "list_databases",
        "get_server",
        "get_service",
        "get_application",
        "get_database",
        "create_project",
        "create_fullstack_project",
        "deploy_infrastructure_stack",
        "get_application_resources",
        "get_application_logs",
        "get_deployments"
      ]
    }
  }
}

Cursor IDE Setup

# In Cursor, add MCP server:
env COOLIFY_ACCESS_TOKEN="0|your-token" COOLIFY_BASE_URL="https://your-server.com" node /path/to/coolify-mcp-enhanced/dist/index.js

Other MCP-Compatible Tools

The server works with any MCP-compatible AI tool. Just provide:

Command: node /path/to/coolify-mcp-enhanced/dist/index.js
Environment: Your COOLIFY_ACCESS_TOKEN and COOLIFY_BASE_URL

💬 Example AI Conversations

Once set up, you can have natural conversations like:

🚀 Deploy a Full-Stack Application

"Create a new project called 'my-webapp' and deploy it with PostgreSQL database, Redis cache, and MinIO storage on my Coolify server."

📊 Monitor Your Applications

"Show me all my applications and their current resource usage. If any app is using more than 80% CPU, show me its recent logs."

🔧 Manage Environment Variables

"Update the environment variables for my 'api-server' application to include DATABASE_URL and REDIS_URL, then restart it."

🐳 Deploy Custom Services

"Deploy this Docker Compose configuration as a new service in my 'production' project."

🛠️ Available Tools & Commands

Project & Server Management

| Tool | Description | Example Use | |------|-------------|-------------| | list_servers | List all your Coolify servers | "Show me all my servers" | | list_projects | List all projects | "What projects do I have?" | | create_project | Create a new project | "Create a project called 'blog'" |

Application Management

| Tool | Description | Example Use | |------|-------------|-------------| | list_applications | List all applications | "Show all my apps" | | create_application | Deploy new application | "Deploy my GitHub repo as an app" | | get_application_logs | View application logs | "Show logs for my API server" | | get_application_resources | Monitor resource usage | "How much CPU is my app using?" |

Infrastructure Deployment

| Tool | Description | Example Use | |------|-------------|-------------| | create_fullstack_project | Create project with common services | "Set up a full-stack project" | | deploy_infrastructure_stack | Deploy PostgreSQL, Redis, MinIO | "Add database and cache to my project" |

Service Management

| Tool | Description | Example Use | |------|-------------|-------------| | list_services | List all services | "What services are running?" | | create_service | Create new service | "Add a WordPress service" | | create_docker_compose_service | Deploy Docker Compose | "Deploy this compose file" |

Database Management

| Tool | Description | Example Use | |------|-------------|-------------| | list_databases | List all databases | "Show my databases" | | create_database | Create new database | "Create a PostgreSQL database" | | update_database | Update database settings | "Change database memory limit" |

Environment & Configuration

| Tool | Description | Example Use | |------|-------------|-------------| | get_application_environment_variables | Get env vars | "Show environment variables" | | update_application_environment_variables | Update env vars | "Update API keys" |

Deployment Management

| Tool | Description | Example Use | |------|-------------|-------------| | get_deployments | List deployments | "Show deployment history" | | cancel_deployment | Cancel deployment | "Stop the failing deployment" | | deploy_application | Deploy application | "Deploy my latest changes" |

🔧 Configuration Examples

Common Coolify Hosting Services

# Coolify Cloud (official)
export COOLIFY_BASE_URL="https://app.coolify.io"

# v0cl.one (popular hosting)
export COOLIFY_BASE_URL="https://s1.v0cl.one"
# or https://s2.v0cl.one, https://s3.v0cl.one, etc.

# Self-hosted Coolify
export COOLIFY_BASE_URL="https://coolify.yourdomain.com"

# Local development
export COOLIFY_BASE_URL="http://localhost:3000"

API Token Permissions

Your Coolify API token should have these permissions:

✅ Read servers - List and view server information
✅ Manage projects - Create and manage projects
✅ Manage applications - Deploy and manage applications
✅ Manage services - Create and manage services
✅ Manage databases - Create and manage databases

✅ Real-World Success Story

This enhanced MCP server has been successfully tested and deployed with a real v0cl.one Coolify instance:

Live Example Configuration

Server: https://s1.v0cl.one
Services Managed: Ghost blog, Docker registry, MySQL database
Status: ✅ All enhanced tools working perfectly
Performance: Real-time monitoring and management through AI

Verified Capabilities

✅ Server Management - Successfully lists and manages Coolify servers
✅ Service Monitoring - Real-time status of Ghost blog and Docker registry
✅ Database Management - MySQL database monitoring and management
✅ Enhanced Tools - All 15+ new tools tested and working
✅ AI Integration - Natural language commands working in Kiro IDE

What Users Are Saying

"The enhanced MCP server makes managing my v0cl.one Coolify instance incredibly easy. I can now deploy and monitor everything through simple AI conversations!"

🧪 Testing & Troubleshooting

Test Your Setup

# Basic connectivity test
node test-mcpaas.js

# Test specific functionality
echo '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"list_servers","arguments":{}}}' | node dist/index.js

Common Issues

❌ "Failed to connect to Coolify server"

Check your COOLIFY_BASE_URL - Make sure it's accessible
Verify your API token - Ensure it's valid and has permissions
Check network connectivity - Ensure you can reach the server

❌ "Authentication required"

Regenerate your API token in Coolify dashboard
Check token format - Should start with 0| or similar
Verify token permissions - Ensure it has required scopes

❌ "Tool not found"

Rebuild the server - Run npm run build
Check MCP client configuration - Ensure correct path and environment

Debug Mode

# Enable detailed logging
DEBUG=coolify:* node dist/index.js

🤝 Contributing

We welcome contributions! This enhanced server builds upon the excellent foundation of the original Coolify MCP Server.

Fork the repository
Create a feature branch
Add tests for new functionality
Submit a pull request

📚 Documentation

Original Coolify MCP Server - The foundation this builds upon
Coolify Documentation - Learn about Coolify platform
MCP Specification - Model Context Protocol details

📄 License

MIT License - Enhanced version maintains the same license as the original.

🙏 Acknowledgments

Stuart Mason - Original Coolify MCP Server creator
Coolify Team - Amazing self-hosting platform
Anthropic - Model Context Protocol specification

🔗 Links

Ready to supercharge your Coolify workflow with AI? 🚀 Get started now!

Made with ❤️ for the Coolify community