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)

• 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

• Update and retrieve environment variables
• Configure domains and SSL certificates
• Retrieve application logs for debugging
• Manage sensitive and build-time variables

• List and monitor servers
• Manage teams and permissions
• View deployed services (databases, caches, etc.)
• Test API connectivity and system health

• 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!

• 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

• Node.js 18+
• A running Coolify Self-hosted instance
• Coolify API token with appropriate permissions

1. Clone or download this repository

   git clone <repository-url>
   cd coolify-mcp-server

2. Install dependencies

   npm install

3. Configure environment variables

   cp .env.example .env
   # Edit .env with your Coolify instance details

4. Build the project

   npm run build

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

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.

npm run dev

npm start

This MCP server provides 4 unified tools for AI assistants, optimized for the 128-tool limit in VS Code:

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

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

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

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!

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"

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

This MCP server interacts with the Coolify API. For detailed API documentation, visit:

• Coolify API Documentation
• Coolify Documentation

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

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

npm run build

npm run type-check

node test-docs.js

This will test all built-in documentation features without requiring a Coolify connection.

# 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

npm run clean

This MCP server is designed to work with:

• Coolify v4.x (Self-hosted)
• API version: v1

• 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

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

Enable debug logging by setting:

NODE_ENV=development npm run dev

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

MIT License - see LICENSE file for details

• Coolify Documentation
• Coolify GitHub
• Model Context Protocol

• ✅ 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