Coolify MCP Server

# 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 ```bash git clone https://github.com/your-org/coolify-mcp-server.git cd coolify-mcp-server npm install npm run build ``` ### Option 2: Docker (Recommended) ```bash docker pull ghcr.io/your-org/coolify-mcp-server:latest ``` ## ⚙️ Configuration Create a `.env` file based on `.env.example`: ```env # 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 1. Log into your Coolify instance 2. Go to Settings → API Tokens 3. Create a new token with permissions for: - Projects: Read/Write - Applications: Read/Write/Delete - Deployments: Read/Write ## 🏃 Running the Server ### Development ```bash npm run dev ``` ### Production ```bash npm run build npm start ``` ### Docker ```bash 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: ```json { "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 projects - `coolify.create_project` - Create a new project ### Applications - `coolify.list_apps` - List applications in a project - `coolify.get_app` - Get application details - `coolify.create_app` - Create a new application - `coolify.update_app` - Update an application - `coolify.delete_app` - Delete an application ### Deployments - `coolify.deploy_app` - Deploy an application - `coolify.get_deployment_status` - Check deployment status - `coolify.get_deployment_logs` - Get deployment logs ### Templates - `coolify.deploy_template` - Deploy from a pre-configured template - `coolify.list_templates` - List available templates ### Safety - `coolify.check_quota` - Check project quota - `coolify.check_name_conflicts` - Check if application name is available ## 🎯 Quick Start Examples ### Deploy Plausible Analytics ```javascript // 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 ```javascript // 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](./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](./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: ```json { "success": true, "data": { ... } } ``` Or for errors: ```json { "success": false, "error": { "code": "ERROR_CODE", "message": "Human-readable error description" } } ``` ### Error Codes - `UNAUTHORIZED` - Invalid API token - `FORBIDDEN` - Insufficient permissions - `NOT_FOUND` - Resource doesn't exist - `CONFLICT` - Resource conflict (e.g., duplicate name) - `VALIDATION_ERROR` - Invalid input data - `RATE_LIMIT` - Too many requests - `QUOTA_EXCEEDED` - Project quota exceeded - `NETWORK_ERROR` - Failed to connect to Coolify - `UNKNOWN_ERROR` - Unexpected error ## 🤝 Contributing 1. Fork the repository 2. Create a feature branch: `git checkout -b feature/amazing-feature` 3. Commit your changes: `git commit -m 'Add amazing feature'` 4. Push to the branch: `git push origin feature/amazing-feature` 5. Open a Pull Request ### Development Setup ```bash # 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](LICENSE) file for details. ## 🆘 Support - 📖 [Documentation](./docs/) - 🐛 [Issue Tracker](https://github.com/your-org/coolify-mcp-server/issues) - 💬 [Discussions](https://github.com/your-org/coolify-mcp-server/discussions) ## 🙏 Acknowledgments - [Coolify](https://coolify.io) - The amazing self-hosting platform - [Model Context Protocol](https://modelcontextprotocol.io) - The protocol that makes this possible - All contributors and users of this project --- Built with ❤️ by the community