Coolify MCP Server

# Coolify MCP Server A **4-tool unified** Model Context Protocol (MCP) server for [Coolify](https://coolify.io/) deployment platform integration. This server enables AI assistants to interact with Coolify Self-hosted instances for application deployment, management, and monitoring. **🎯 Optimized for VS Code's 128-tool limit with 87% reduction (19→4 tools)** ## Features ### 🚀 Application Management - Deploy applications with optional force deployment and branch selection - Get detailed application information and status - List applications with filtering capabilities - Start, stop, and restart applications - Monitor deployment status and health - Create new applications ### 🔧 Environment & Configuration - Update and retrieve environment variables - Configure domains and SSL certificates - Retrieve application logs for debugging - Manage sensitive and build-time variables ### 🖥️ System Management - List and monitor servers - Manage teams and permissions - View deployed services (databases, caches, etc.) - Test API connectivity and system health ### 📚 Built-in Documentation - **Search Documentation**: Find relevant Coolify guides and references - **API Reference**: Access comprehensive API documentation with examples - **Troubleshooting Guides**: Get help for common deployment and configuration issues - **Topic-specific Help**: Get targeted documentation for specific features *Perfect for AI agents without Context7 MCP access - no external documentation dependencies required!* ### 🧪 Complete Testing Suite - **100% Test Success Rate**: Comprehensive integration tests - **Demo Environment**: Full Coolify setup with Docker Compose - **Browser Automation**: MCP Playwright integration - **Real API Testing**: Direct Coolify instance validation ## Prerequisites - Node.js 18+ - A running Coolify Self-hosted instance - Coolify API token with appropriate permissions ## Installation 1. **Clone or download this repository** ```bash git clone <repository-url> cd coolify-mcp-server ``` 2. **Install dependencies** ```bash npm install ``` 3. **Configure environment variables** ```bash cp .env.example .env # Edit .env with your Coolify instance details ``` 4. **Build the project** ```bash npm run build ``` ## Configuration ### Environment Variables Create a `.env` file with the following variables: ```env # Required: Your Coolify instance URL COOLIFY_BASE_URL=https://your-coolify-instance.com # Required: API token from Coolify COOLIFY_API_TOKEN=your-api-token-here # Optional: Team ID for scoped access COOLIFY_TEAM_ID=your-team-id ``` ### Getting Your API Token 1. Log into your Coolify dashboard 2. Go to **Settings** → **Keys & Tokens** → **API Tokens** 3. Click **Create New Token** 4. Choose permissions: - `read-only`: View data only - `read:sensitive`: View sensitive data - `*`: Full access (recommended for automation) 5. Copy the generated token to your `.env` file ⚠️ **Security Note**: API tokens are shown only once. Store them securely and never commit them to version control. ## Usage ### Development Mode ```bash npm run dev ``` ### Production Mode ```bash npm start ``` ### Integration with AI Assistants This MCP server provides **4 unified tools** for AI assistants, optimized for the 128-tool limit in VS Code: #### 📱 Application Management (`coolify_application_management`) **Unified tool with 8 actions:** - `deploy` - Deploy an application with optional force deployment and branch selection - `get` - Get detailed application information - `list` - List all applications with filtering capabilities - `status` - Get deployment status and health - `start` - Start an application - `stop` - Stop an application - `restart` - Restart an application - `create` - Create a new application #### ⚙️ Environment Configuration (`coolify_environment_configuration`) **Unified tool for environment and domain management:** - `env_vars` - Update and retrieve environment variables - `domains` - Configure domains and SSL certificates - `logs` - Retrieve application logs for debugging #### 🖥️ System Management (`coolify_system_management`) **Unified tool for server and infrastructure:** - `servers` - List and monitor servers - `teams` - Manage teams and permissions - `services` - View deployed services (databases, caches, etc.) - `health_check` - Test API connectivity and system health #### 📚 Documentation (`coolify_documentation`) **Unified documentation tool with 6 actions:** - `search` - Search built-in Coolify documentation - `get` - Get documentation for specific topics - `api_reference` - Get API reference documentation with examples - `troubleshooting` - Get troubleshooting guides for common issues - `topics` - List available documentation topics - `api` - Get API endpoint documentation *Perfect for AI agents without Context7 MCP access - no external documentation dependencies required!* ### Example Usage Here are some example commands you can use with AI assistants using the **unified tools**: **Application Management:** ``` "Deploy my application with ID 'app-123' using force deployment" "Get details for application 'my-web-app'" "List all running applications" "Check the status of application 'app-456'" "Start application 'my-backend'" "Restart application 'frontend-app'" ``` **Environment Configuration:** ``` "Update environment variables for 'app-789': set DATABASE_URL and REDIS_URL" "Get current environment variables for 'my-app'" "Set the domain 'example.com' for application 'app-456' with HTTPS enabled" "Get the logs for application 'my-web-app'" ``` **System Management:** ``` "List all servers and their status" "Get information about teams" "Show all running services" "Check system health and API connectivity" ``` **Documentation:** ``` "Search documentation for 'deployment failed'" "Get troubleshooting help for SSL certificate issues" "Show me API reference for environment variables" "List all available documentation topics" "Get API documentation for applications endpoint" ``` ### Documentation Features The MCP server includes comprehensive built-in documentation accessed through the unified `coolify_documentation` tool: ```javascript // Search for deployment-related documentation await callTool('coolify_documentation', { action: 'search', query: 'deployment failed' }); // Get API reference for applications endpoint await callTool('coolify_documentation', { action: 'api_reference', endpoint: 'applications' }); // Get troubleshooting help for SSL issues await callTool('coolify_documentation', { action: 'troubleshooting', issue: 'ssl certificate' }); // List all available topics await callTool('coolify_documentation', { action: 'topics' }); // Get general documentation on environment variables await callTool('coolify_documentation', { action: 'get', topic: 'environment variables' }); ``` **Built-in Documentation Covers:** - API Reference with examples - Step-by-step deployment guides - Environment variable configuration - Domain and SSL setup - Common troubleshooting scenarios ## API Reference This MCP server interacts with the Coolify API. For detailed API documentation, visit: - [Coolify API Documentation](https://coolify.io/docs/api) - [Coolify Documentation](https://coolify.io/docs/) ## Architecture ``` coolify-mcp-server/ ├── src/ │ ├── index.ts # Main MCP server (unified version) │ ├── types/ │ │ ├── coolify.ts # Coolify API types │ │ └── mcp.ts # MCP tool schemas │ ├── utils/ │ │ └── coolify-client.ts # Coolify API client │ └── tools/ │ ├── application-unified.ts # Unified application management │ ├── environment-unified.ts # Unified environment & domain tools │ ├── system-unified.ts # Unified system management │ └── documentation-unified.ts # Unified documentation tools ├── demo-server/ │ ├── docker-compose.yml # Complete Coolify demo environment │ └── DEMO-SETUP.md # Demo setup instructions ├── .env.example # Environment configuration template ├── test-*.js # Comprehensive test suites ├── tsconfig.json # TypeScript configuration └── package.json # Project dependencies ``` ## Demo Environment This project includes a **complete Coolify demo environment** for testing: ```bash cd demo-server docker compose up -d ``` **Includes:** - ✅ Coolify latest version - ✅ PostgreSQL database - ✅ Redis cache - ✅ Soketi WebSocket server - ✅ Pre-configured demo users - ✅ Web interface at http://localhost:8000 **Demo Credentials:** - Email: `test@example.com` - Password: `password123` ## Development ### Building ```bash npm run build ``` ### Type Checking ```bash npm run type-check ``` ### Testing Documentation Features ```bash node test-docs.js ``` This will test all built-in documentation features without requiring a Coolify connection. ### Testing with Demo Environment ```bash # Start the demo environment cd demo-server && docker compose up -d # Run comprehensive tests npm test ``` **Test Suites:** - `test-integration.js` - Docker environment and build tests - `test-mcp-simple.js` - MCP server functionality tests - `test-web-interface.js` - Playwright browser automation tests - `test-real-coolify.js` - Real Coolify integration tests **Expected Results:** 100% test success rate ### Cleaning ```bash npm run clean ``` ## Supported Coolify Versions This MCP server is designed to work with: - Coolify v4.x (Self-hosted) - API version: v1 ## Security Considerations - **API Tokens**: Store API tokens securely using environment variables - **Network Access**: Ensure your Coolify instance is accessible from where this MCP server runs - **Permissions**: Use appropriate API token permissions based on your use case - **HTTPS**: Always use HTTPS for production Coolify instances ## Troubleshooting ### Common Issues 1. **Connection Failed** - Verify `COOLIFY_BASE_URL` is correct and accessible - Check that API token has proper permissions - Ensure Coolify instance is running 2. **Permission Denied** - Verify API token has sufficient permissions - Check if team ID is required for your setup 3. **Application Not Found** - Verify application ID is correct - Ensure you have access to the application ### Debug Mode Enable debug logging by setting: ```bash NODE_ENV=development npm run dev ``` ## Contributing 1. Fork the repository 2. Create a feature branch 3. Make your changes 4. Add tests if applicable 5. Submit a pull request ## License MIT License - see LICENSE file for details ## Support - [Coolify Documentation](https://coolify.io/docs/) - [Coolify GitHub](https://github.com/coollabsio/coolify) - [Model Context Protocol](https://modelcontextprotocol.io/) ## Changelog ### v1.0.0 - ✅ **4 Unified Tools**: Optimized for VS Code's 128-tool limit - ✅ **Complete Demo Environment**: Docker Compose setup with working Coolify instance - ✅ **100% Test Coverage**: Comprehensive test suites with 100% success rate - ✅ **Built-in Documentation**: No external dependencies required - ✅ **Browser Automation**: MCP Playwright integration for testing - ✅ **Application Management**: Deploy, manage, and monitor applications - ✅ **Environment Configuration**: Manage env vars, domains, and logs - ✅ **System Management**: Server, team, and service management - ✅ **Full TypeScript Support**: Complete type safety with Zod validation