Coolify MCP Server

A comprehensive Model Context Protocol (MCP) server for the Coolify API. This server enables AI assistants to manage infrastructure, applications, databases, services, and more through your self-hosted Coolify PaaS platform.

Compatibility: Tested with Coolify version 4.0.0-beta.418

👋 Open for Opportunities!
I'm actively seeking new opportunities and collaborations. If you have interesting projects or job opportunities, feel free to reach out!
📧 Contact: pashvc@gmail.com

Prerequisites

• Node.js 18 or higher

• Coolify Base URL

• Coolify API token

Features

Core Management

• Teams: List teams, get team details, view team members

• Projects: Create, list, update, and delete projects

• Servers: Create servers, validate connections, view resources and domains

• Private Keys: Manage SSH keys for server access

Applications

• Full CRUD operations (create, read, update, delete)

• Lifecycle management (start, stop, restart)

• Execute commands in containers

• View application logs

• Git integration (repository, branch, commit management)

• Resource limits configuration (memory, CPU)

• Health check configuration

Databases

• Support for PostgreSQL, MySQL, MariaDB, MongoDB, and Redis

• Create and manage database instances

• Configure database-specific settings

• Lifecycle management (start, stop, restart)

• Resource limits and public port configuration

Services

• Deploy pre-configured services (Plausible, Umami, n8n, etc.)

• Service lifecycle management

• Configuration updates

Environment Variables

• Manage environment variables for applications, services, and databases

• Support for build-time and runtime variables

• Preview deployment variables

• Shared variables across environments

Deployments

• List all deployments

• Get deployment details and logs

• Trigger deployments via webhook

• Support for Docker image tags

Developer Experience

• Pre-configured prompts for common workflows

• Comprehensive error handling with detailed messages

• TypeScript support with full type safety

• Integration with MCP Inspector for debugging

• Robust API response handling for different Coolify versions

• Extensive test coverage with both unit and integration tests

Installation

Configuration

The server requires two environment variables:

• COOLIFY_BASE_URL: The base URL of your Coolify instance

• COOLIFY_TOKEN: Your Coolify API token

Getting an API Token

1. Go to your Coolify instance

2. Navigate to Keys & Tokens / API tokens

3. Create a new token with the following required permissions:

   • read (for fetching information)

   • write (for managing resources)

   • deploy (for deployment operations)

Usage

In MCP Settings

Add the following to your MCP settings configuration:

Windows Cline users may need the following:

Available Tools

Version & Health

• coolify_version: Get Coolify version information

• coolify_health: Check Coolify API health status

Teams

• list_teams: List all teams

• get_team: Get details of a specific team

• get_current_team: Get current team details

• get_current_team_members: Get current team members

Servers

• list_servers: List all servers

• create_server: Create a new server

• validate_server: Validate server configuration

• get_server_resources: Get server resources

• get_server_domains: Get server domains

Projects

• list_projects: List all projects

• get_project: Get project details

• create_project: Create a new project

• update_project: Update project settings

• delete_project: Delete a project

Applications

• list_applications: List all applications

• get_application: Get application details

• create_application: Create a new application

• update_application: Update application settings

• delete_application: Delete an application

• start_application: Start an application

• stop_application: Stop an application

• restart_application: Restart an application

• execute_command: Execute command in application container

• get_application_logs: Get application logs

Databases

• list_databases: List all databases

• get_database: Get database details

• create_database: Create a new database

• update_database: Update database settings

• delete_database: Delete a database

• start_database: Start a database

• stop_database: Stop a database

• restart_database: Restart a database

Services

• list_services: List all services

• get_service: Get service details

• create_service: Create a new service

• update_service: Update service settings

• delete_service: Delete a service

• start_service: Start a service

• stop_service: Stop a service

• restart_service: Restart a service

Environment Variables

• list_environment_variables: List environment variables

• create_environment_variable: Create a new environment variable

• update_environment_variable: Update an environment variable

• delete_environment_variable: Delete an environment variable

Deployments

• list_deployments: List all deployments

• get_deployment: Get deployment details

• deploy_webhook: Trigger deployment via webhook

Private Keys

• list_private_keys: List all private keys

• create_private_key: Create a new private key

• update_private_key: Update a private key

• delete_private_key: Delete a private key

Pre-configured Prompts

The server includes helpful prompts for common workflows:

• deploy-git-app: Deploy a new application from a Git repository

• setup-database: Set up a new database with proper configuration

• deploy-service: Deploy a pre-configured service

• environment-setup: Set up environment variables for an application

• server-health-check: Comprehensive health check of all servers

• backup-database: Create a backup of a database

• scale-application: Scale an application by adjusting resources

• setup-ssl: Configure SSL/TLS for an application

• migrate-application: Migrate an application between servers

• troubleshoot-deployment: Troubleshoot a failed deployment

Development

Building from Source

Development Scripts

• npm run build: Build the TypeScript project

• npm run watch: Build and watch for changes

• npm test: Run all tests

• npm run test:watch: Run tests in watch mode

• npm run test:coverage: Run tests with coverage report

• npm run test:integration: Run integration tests only (requires env vars)

• npm run inspector: Launch MCP Inspector for debugging

Troubleshooting

Common Issues

• 404 Errors: Some endpoints may not be available in all Coolify versions. The server automatically handles different response formats across versions.

• Authentication Errors: Ensure your API token has the required permissions (read, write, deploy).

• Connection Issues: Verify your COOLIFY_BASE_URL is correct and accessible.

• Environment Variables: Make sure both COOLIFY_BASE_URL and COOLIFY_TOKEN are set correctly.

Testing Your Setup

API Compatibility

The server handles different response formats automatically:

• Version endpoint: Supports both string and object responses

• List endpoints: Handles both direct arrays and paginated responses

• Health endpoint: Adapts to different status response formats

• Error handling: Robust parsing of various error message formats

License

MIT