dazeb/coolify-mcp-enhanced

🚀 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:

1. ✅ Getting your Coolify API token
2. ✅ Configuring your server URL
3. ✅ Setting up your AI assistant
4. ✅ Testing the connection

Option B: Manual Setup

Step 1: Get Your Coolify API Token

1. Log into your Coolify dashboard (e.g., https://your-coolify-server.com)
2. Go to API Tokens (usually in Settings or Profile)
3. Create a new token with appropriate permissions
4. 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

Application Management

Infrastructure Deployment

Service Management

Database Management

Environment & Configuration

Deployment Management

🔧 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.

1. Fork the repository
2. Create a feature branch
3. Add tests for new functionality
4. 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

• GitHub Repository
• Issues & Support
• Coolify Platform
• MCP Documentation

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

Made with ❤️ for the Coolify community