Coolify MCP Server
A Model Context Protocol (MCP) server that exposes Coolify API functionality as safe, structured tools for AI agents. This enables AI-driven app marketplaces where users can deploy applications on Coolify with a single click.
🚀 Features
- Project Management: List, create, and manage Coolify projects
- Application Lifecycle: Create, update, delete, and manage applications
- Deployment Control: Deploy applications and monitor their status
- Template Marketplace: Pre-configured templates for popular applications
- Safety Guardrails: Quota checking, name conflict detection, and resource limits
- Comprehensive Logging: Full audit trail of all AI operations
📋 Prerequisites
- Node.js 18+
- A running Coolify instance
- Coolify API token with appropriate permissions
- Docker (for running the MCP server)
🛠️ Installation
Option 1: Clone and Build
git clone https://github.com/your-org/coolify-mcp-server.git
cd coolify-mcp-server
npm install
npm run build
Option 2: Docker (Recommended)
docker pull ghcr.io/your-org/coolify-mcp-server:latest
⚙️ Configuration
Create a .env file based on .env.example:
# Required
COOLIFY_API_URL=https://your-coolify-instance.com
COOLIFY_API_TOKEN=your-api-token-here
# Optional
COOLIFY_DEFAULT_TEAM_ID=
COOLIFY_MAX_APPS_PER_PROJECT=10
LOG_LEVEL=info
Getting Your Coolify API Token
- Log into your Coolify instance
- Go to Settings → API Tokens
- Create a new token with permissions for:
- Projects: Read/Write
- Applications: Read/Write/Delete
- Deployments: Read/Write
🏃 Running the Server
Development
npm run dev
Production
npm run build
npm start
Docker
docker run \
-e COOLIFY_API_URL=https://coolify.example.com \
-e COOLIFY_API_TOKEN=your-token \
-e COOLIFY_MAX_APPS_PER_PROJECT=20 \
ghcr.io/your-org/coolify-mcp-server:latest
🔧 MCP Client Configuration
Add to your MCP client configuration:
{
"mcpServers": {
"coolify": {
"command": "node",
"args": ["/path/to/coolify-mcp-server/dist/index.js"],
"env": {
"COOLIFY_API_URL": "https://your-coolify-instance.com",
"COOLIFY_API_TOKEN": "your-api-token",
"COOLIFY_MAX_APPS_PER_PROJECT": "10"
}
}
}
}
📚 Available Tools
Projects
coolify.list_projects- List all projectscoolify.create_project- Create a new project
Applications
coolify.list_apps- List applications in a projectcoolify.get_app- Get application detailscoolify.create_app- Create a new applicationcoolify.update_app- Update an applicationcoolify.delete_app- Delete an application
Deployments
coolify.deploy_app- Deploy an applicationcoolify.get_deployment_status- Check deployment statuscoolify.get_deployment_logs- Get deployment logs
Templates
coolify.deploy_template- Deploy from a pre-configured templatecoolify.list_templates- List available templates
Safety
coolify.check_quota- Check project quotacoolify.check_name_conflicts- Check if application name is available
🎯 Quick Start Examples
Deploy Plausible Analytics
// First, check if the name is available
await checkNameConflicts({
projectId: "proj-123",
name: "plausible-analytics"
});
// Deploy the template
const result = await deployTemplate({
templateName: "plausible",
projectId: "proj-123",
appName: "plausible-analytics",
environment: {
BASE_URL: "https://analytics.example.com",
SECRET_KEY_BASE: "your-secret-key",
POSTGRES_URL: "postgresql://..."
}
});
Deploy Custom Application
// Create a new application
const app = await createApp({
projectId: "proj-123",
name: "my-react-app",
type: "dockerfile",
gitRepository: {
url: "https://github.com/user/react-app.git",
branch: "main"
},
environment: {
NODE_ENV: "production"
},
ports: [3000]
});
// Deploy it
const deployment = await deployApp({ id: app.id });
📦 Available Templates
| Template | Description | Type | Services |
|---|---|---|---|
| plausible | Privacy-friendly analytics | Docker Image | PostgreSQL |
| strapi | Headless CMS | Git | PostgreSQL, MySQL |
| saleor | E-commerce platform | Docker Image | PostgreSQL, Redis |
| n8n | Workflow automation | Docker Image | PostgreSQL, Redis |
| uptime-kuma | Monitoring tool | Docker Image | - |
| gitlab | Git repository manager | Docker Image | PostgreSQL, Redis |
| rocketchat | Communication platform | Docker Image | MongoDB |
| bookstack | Documentation platform | Docker Image | MySQL, PostgreSQL |
See examples/tool-calls.md for detailed examples.
🔒 Security
- API tokens are stored server-side and never exposed to AI agents
- All inputs are validated with strict schemas
- Project-level isolation prevents cross-project access
- Built-in quota and rate limiting
- Comprehensive audit logging
See docs/SECURITY.md for detailed security considerations.
📝 API Reference
The MCP server exposes the following endpoints through the Model Context Protocol:
Response Format
All responses follow this structure:
{
"success": true,
"data": { ... }
}
Or for errors:
{
"success": false,
"error": {
"code": "ERROR_CODE",
"message": "Human-readable error description"
}
}
Error Codes
UNAUTHORIZED- Invalid API tokenFORBIDDEN- Insufficient permissionsNOT_FOUND- Resource doesn't existCONFLICT- Resource conflict (e.g., duplicate name)VALIDATION_ERROR- Invalid input dataRATE_LIMIT- Too many requestsQUOTA_EXCEEDED- Project quota exceededNETWORK_ERROR- Failed to connect to CoolifyUNKNOWN_ERROR- Unexpected error
🤝 Contributing
- Fork the repository
- Create a feature branch:
git checkout -b feature/amazing-feature - Commit your changes:
git commit -m 'Add amazing feature' - Push to the branch:
git push origin feature/amazing-feature - Open a Pull Request
Development Setup
# Install dependencies
npm install
# Run in development mode
npm run dev
# Run tests
npm test
# Lint code
npm run lint
# Format code
npm run format
📄 License
This project is licensed under the MIT License - see the LICENSE file for details.
🆘 Support
🙏 Acknowledgments
- Coolify - The amazing self-hosting platform
- Model Context Protocol - The protocol that makes this possible
- All contributors and users of this project
Built with ❤️ by the community