README.md•12.9 kB
# 🚀 Enhanced Coolify MCP Server
A powerful, enhanced Model Context Protocol (MCP) server for [Coolify](https://coolify.io/) 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](https://github.com/StuMason/coolify-mcp) 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)
```bash
# 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
```bash
# 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
```bash
# 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
```bash
# Test basic functionality
node test-mcpaas.js
# You should see:
# ✅ GitHub Repo: PASS
# ✅ Basic connectivity working
```
### Step 5: Quick Verification
```bash
# 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:
```bash
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`:
```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:
```json
{
"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
```bash
# 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
```bash
# 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
```bash
# 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
```bash
# 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](https://github.com/StuMason/coolify-mcp)** - The foundation this builds upon
- **[Coolify Documentation](https://coolify.io/docs)** - Learn about Coolify platform
- **[MCP Specification](https://spec.modelcontextprotocol.io/)** - Model Context Protocol details
## 📄 License
MIT License - Enhanced version maintains the same license as the original.
## 🙏 Acknowledgments
- **[Stuart Mason](https://github.com/StuMason)** - Original Coolify MCP Server creator
- **[Coolify Team](https://coolify.io/)** - Amazing self-hosting platform
- **[Anthropic](https://www.anthropic.com/)** - Model Context Protocol specification
## 🔗 Links
- **[GitHub Repository](https://github.com/dazeb/coolify-mcp-enhanced)**
- **[Issues & Support](https://github.com/dazeb/coolify-mcp-enhanced/issues)**
- **[Coolify Platform](https://coolify.io/)**
- **[MCP Documentation](https://modelcontextprotocol.io/)**
---
**Ready to supercharge your Coolify workflow with AI?**
🚀 **[Get started now!](#quick-start-guide)**
*Made with ❤️ for the Coolify community*