Coolify MCP Server
A 4-tool unified Model Context Protocol (MCP) server for Coolify 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
-
Clone or download this repository
git clone <repository-url> cd coolify-mcp-server -
Install dependencies
npm install -
Configure environment variables
cp .env.example .env # Edit .env with your Coolify instance details -
Build the project
npm run build
Configuration
Environment Variables
Create a .env file with the following variables:
# 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
- Log into your Coolify dashboard
- Go to Settings → Keys & Tokens → API Tokens
- Click Create New Token
- Choose permissions:
read-only: View data onlyread:sensitive: View sensitive data*: Full access (recommended for automation)
- Copy the generated token to your
.envfile
⚠️ Security Note: API tokens are shown only once. Store them securely and never commit them to version control.
Usage
Development Mode
npm run dev
Production Mode
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 selectionget- Get detailed application informationlist- List all applications with filtering capabilitiesstatus- Get deployment status and healthstart- Start an applicationstop- Stop an applicationrestart- Restart an applicationcreate- Create a new application
⚙️ Environment Configuration (coolify_environment_configuration)
Unified tool for environment and domain management:
env_vars- Update and retrieve environment variablesdomains- Configure domains and SSL certificateslogs- Retrieve application logs for debugging
🖥️ System Management (coolify_system_management)
Unified tool for server and infrastructure:
servers- List and monitor serversteams- Manage teams and permissionsservices- 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 documentationget- Get documentation for specific topicsapi_reference- Get API reference documentation with examplestroubleshooting- Get troubleshooting guides for common issuestopics- List available documentation topicsapi- 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:
// 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:
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:
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
npm run build
Type Checking
npm run type-check
Testing Documentation Features
node test-docs.js
This will test all built-in documentation features without requiring a Coolify connection.
Testing with Demo Environment
# 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 teststest-mcp-simple.js- MCP server functionality teststest-web-interface.js- Playwright browser automation teststest-real-coolify.js- Real Coolify integration tests
Expected Results: 100% test success rate
Cleaning
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
-
Connection Failed
- Verify
COOLIFY_BASE_URLis correct and accessible - Check that API token has proper permissions
- Ensure Coolify instance is running
- Verify
-
Permission Denied
- Verify API token has sufficient permissions
- Check if team ID is required for your setup
-
Application Not Found
- Verify application ID is correct
- Ensure you have access to the application
Debug Mode
Enable debug logging by setting:
NODE_ENV=development npm run dev
Contributing
- Fork the repository
- Create a feature branch
- Make your changes
- Add tests if applicable
- Submit a pull request
License
MIT License - see LICENSE file for details
Support
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