coolify-mcp-server

ignitabull18/coolify-mcp-server

3.2

If you are the rightful owner of coolify-mcp-server and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to henry@mcphub.com.

Coolify MCP Server provides comprehensive access to the Coolify API, enabling AI assistants to manage various infrastructure components through a unified platform.

Tools
5
Resources
0
Prompts
0

Coolify MCP Server šŸš€

A comprehensive Model Context Protocol (MCP) server that provides complete access to the Coolify API. This server enables AI assistants to manage applications, databases, services, servers, and more through Coolify's platform.

Features āœØ

šŸ› ļø 90+ API Tools

Complete coverage of all Coolify endpoints with type-specific routing:

  • Applications: Create, deploy, update, start/stop/restart, environment variables, logs
  • Databases: PostgreSQL, MySQL, MariaDB, MongoDB, Redis, DragonFly, KeyDB, ClickHouse
  • Services: One-click services, custom deployments, lifecycle management
  • Servers: Validation, resource monitoring, domain management
  • Projects: Organization, environments, team collaboration
  • Deployments: Monitoring, history, automated deployments
  • Teams & Access: User management, private keys, permissions

šŸ“Š 10+ Resources

Access Coolify data through standardized URIs:

  • coolify://applications/{uuid} - Application details
  • coolify://databases/{uuid} - Database information
  • coolify://services/{uuid} - Service configurations
  • coolify://servers/{uuid} - Server details
  • coolify://projects/{uuid} - Project information
  • coolify://overview - Complete instance overview
  • coolify://status - Health and status information

šŸ’” 8+ Workflow Prompts

Guided workflows for common DevOps tasks:

  • deploy-application - Complete deployment workflow
  • troubleshoot-deployment - Diagnostic and problem solving
  • setup-new-project - Project setup guidance
  • database-setup - Database configuration and best practices
  • setup-monitoring - Monitoring and alerting setup
  • maintenance-workflow - Safe maintenance procedures
  • performance-optimization - Performance analysis and tuning
  • disaster-recovery-plan - DR planning and procedures

Installation šŸ“¦

  1. Clone the repository:
git clone <repository-url>
cd coolify-mcp-server
  1. Install dependencies:
npm install
  1. Configure environment variables:
cp .env.example .env

Edit .env with your Coolify details:

COOLIFY_BASE_URL=https://app.coolify.io/api/v1
COOLIFY_API_TOKEN=your_api_token_here

For self-hosted Coolify instances:

COOLIFY_BASE_URL=https://your-coolify-instance.com/api/v1
COOLIFY_API_TOKEN=your_api_token_here
  1. Build the server:
npm run build

Usage šŸŽÆ

Development Mode

npm run dev

Production Mode

npm start

Testing with MCP Inspector

npm run inspector

Remote HTTP Server (NEW!)

For hosting the MCP server remotely and connecting multiple clients:

# Install additional dependencies
npm install express @types/express

# Build and start HTTP server
npm run build
npm run start:http  # Starts on http://localhost:3000

Access endpoints:

  • Health: http://localhost:3000/health
  • Info: http://localhost:3000/info
  • MCP: http://localhost:3000/mcp (Server-Sent Events)

See DEPLOYMENT.md for comprehensive remote hosting options including:

  • šŸ”„ Deploy on Coolify (recommended)
  • šŸŽÆ MCPHub Integration (see MCPHUB_INSTALLATION.md)
  • šŸ³ Docker deployment
  • ā˜ļø Cloud platforms (Vercel, Railway, Render)
  • šŸ–„ļø VPS hosting with PM2

Getting Your API Token šŸ”‘

  1. Log into your Coolify instance
  2. Go to Security ā†’ API Tokens
  3. Click Generate API Token
  4. Copy the token and add it to your .env file

MCP Client Configuration šŸ“±

Local Execution (Traditional)

Claude Desktop - Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "coolify": {
      "command": "node",
      "args": ["/path/to/coolify-mcp-server/build/index.js"]
    }
  }
}

VS Code - Add to your VS Code MCP settings:

{
  "mcp": {
    "servers": {
      "coolify": {
        "command": "node",
        "args": ["/path/to/coolify-mcp-server/build/index.js"]
      }
    }
  }
}

Remote HTTP Connection (NEW!)

Claude Desktop - Connect to remotely hosted server:

{
  "mcpServers": {
    "coolify-remote": {
      "url": "https://your-mcp-server.com/mcp"
    }
  }
}

Development/Local HTTP:

{
  "mcpServers": {
    "coolify-local": {
      "url": "http://localhost:3000/mcp"
    }
  }
}

Multiple Environments:

{
  "mcpServers": {
    "coolify-staging": {
      "url": "https://staging-mcp.yourcompany.com/mcp"
    },
    "coolify-production": {
      "url": "https://production-mcp.yourcompany.com/mcp"
    }
  }
}

MCPHub Integration (Recommended for Teams)

If you're using samanhappy/mcphub for centralized MCP server management:

Add to your mcp_settings.json:

{
  "mcpServers": {
    "coolify": {
      "url": "https://your-coolify-mcp.com/mcp",
      "description": "Complete Coolify API integration",
      "enabled": true,
      "group": "infrastructure"
    }
  }
}

Benefits of MCPHub Integration:

  • šŸŽŖ Web Dashboard - Manage servers through UI
  • šŸ‘„ Team Access - Role-based permissions and user management
  • šŸ·ļø Server Groups - Organize by environment or function
  • šŸ”€ Smart Routing - AI-powered tool discovery
  • šŸ“Š Monitoring - Real-time server health and usage analytics
  • šŸ”„ Hot Reloading - Update configurations without restarts

Client connects to MCPHub instead:

{
  "mcpServers": {
    "mcphub": {
      "url": "http://your-mcphub:3000/mcp"
    }
  }
}

See MCPHUB_INSTALLATION.md for complete setup instructions.

API Coverage šŸ“‹

This MCP server provides complete coverage of the Coolify API:

Applications

  • āœ… List applications
  • āœ… Get application details
  • āœ… Create new applications
  • āœ… Update applications
  • āœ… Delete applications
  • āœ… Start/Stop/Restart applications
  • āœ… Deploy applications
  • āœ… Get application logs
  • āœ… Manage environment variables

Databases

  • āœ… Support for all database types
  • āœ… Create, read, update, delete operations
  • āœ… Start/Stop/Restart database instances
  • āœ… Configuration management

Services

  • āœ… One-click service deployment
  • āœ… Custom service configuration
  • āœ… Service lifecycle management
  • āœ… Environment variable management

Servers

  • āœ… Server validation and health checks
  • āœ… Resource monitoring
  • āœ… Domain management
  • āœ… SSH key management

Projects & Teams

  • āœ… Project organization
  • āœ… Team collaboration features
  • āœ… Access control and permissions

Example Usage šŸ’»

Deploy a New Application

// Using the deploy-application prompt
const deployment = await mcpClient.callPrompt('deploy-application', {
  application_name: 'my-awesome-app',
  environment: 'production'
});

Monitor System Health

// Access the overview resource
const overview = await mcpClient.readResource('coolify://overview');
console.log(JSON.parse(overview.content[0].text));

Create a Database

// Use the create-database tool
const database = await mcpClient.callTool('create-database', {
  name: 'my-app-db',
  type: 'postgresql',
  project_uuid: 'project-uuid',
  server_uuid: 'server-uuid'
});

Architecture šŸ—ļø

ā”œā”€ā”€ src/
ā”‚   ā”œā”€ā”€ index.ts           # Main server entry point
ā”‚   ā”œā”€ā”€ api-client.ts      # Coolify API client
ā”‚   ā”œā”€ā”€ types.ts           # TypeScript definitions
ā”‚   ā”œā”€ā”€ tools.ts           # MCP tools (API operations)
ā”‚   ā”œā”€ā”€ resources.ts       # MCP resources (data access)
ā”‚   ā””ā”€ā”€ prompts.ts         # MCP prompts (workflows)
ā”œā”€ā”€ build/                 # Compiled JavaScript
ā””ā”€ā”€ package.json          # Dependencies and scripts

Error Handling šŸ›”ļø

The server includes comprehensive error handling:

  • API connection validation on startup
  • Graceful error responses for failed operations
  • Detailed error messages with context
  • Automatic retry for transient failures

Security Considerations šŸ”’

  • API tokens are loaded from environment variables
  • All API requests use bearer token authentication
  • No sensitive data is logged or exposed
  • Secure HTTPS communication with Coolify API

Contributing šŸ¤

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

Troubleshooting šŸ”§

Common Issues

Connection Errors:

  • Verify your COOLIFY_BASE_URL is correct
  • Check that your COOLIFY_API_TOKEN is valid
  • Ensure your Coolify instance is accessible

Tool Execution Errors:

  • Check the MCP client logs for detailed error messages
  • Verify required parameters are provided
  • Ensure you have proper permissions in Coolify

Debug Mode

Set NODE_ENV=development for verbose logging.

License šŸ“„

MIT License - see LICENSE file for details.

Support šŸ’¬

Built with ā¤ļø for the Coolify and MCP communities# Trigger deployment Wed Aug 6 16:36:06 PDT 2025