Skip to main content
Glama

Coolify MCP Server

by GoCoder7
npmGitHub
TypeScript
518
OverviewInspectNewEndpointsSchemaRelated ServersReviewsScore
Need Help?View Source CodeReport Issue

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

  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

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

  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

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 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:

// 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 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

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:

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

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
Deploy Server
A
security – no known vulnerabilities
F
license - not found
A
quality - confirmed to work

How are these scores calculated?

remote-capable server

The server can be hosted and run remotely because it primarily relies on remote services or has no dependency on the local environment.

Tools

Enables AI assistants to interact with Coolify self-hosted instances for application deployment, management, and monitoring. Features 4 unified tools optimized for VS Code's limits, covering app management, environment configuration, system administration, and built-in documentation.

  1. Features
    1. 🚀 Application Management
    2. 🔧 Environment & Configuration
    3. 🖥️ System Management
    4. 📚 Built-in Documentation
    5. 🧪 Complete Testing Suite
  2. Prerequisites
    1. Installation
      1. Configuration
        1. Environment Variables
        2. Getting Your API Token
      2. Usage
        1. Development Mode
        2. Production Mode
        3. Integration with AI Assistants
        4. Example Usage
        5. Documentation Features
      3. API Reference
        1. Architecture
          1. Demo Environment
            1. Development
              1. Building
              2. Type Checking
              3. Testing Documentation Features
              4. Testing with Demo Environment
              5. Cleaning
            2. Supported Coolify Versions
              1. Security Considerations
                1. Troubleshooting
                  1. Common Issues
                  2. Debug Mode
                2. Contributing
                  1. License
                    1. Support
                      1. Changelog
                        1. v1.0.0

                      Related MCP Servers

                      • CodeSavant

                        twolven
                        -
                        security
                        A
                        license
                        -
                        quality
                        Provides code manipulation, execution, and version control capabilities. It allows AI assistants to read, write, and execute code while maintaining a history of changes.
                        Last updated -
                        9
                        MIT License

                      • Coolify MCP Server

                        StuMason
                        A
                        security
                        F
                        license
                        A
                        quality
                        Enables interaction with Coolify applications and resources through the Coolify API via a standardized interface, supporting application management operations such as listing, starting, stopping, restarting, and deploying.
                        Last updated -
                        11
                        11

                      • Coolify MCP Server

                        StuMason
                        -
                        security
                        F
                        license
                        -
                        quality
                        A Model Context Protocol server that enables AI assistants to interact with Coolify instances through natural language, allowing management of servers, applications, databases, and deployments.
                        Last updated -
                        540
                        42

                      • Coolify MCP Server

                        pavelsukhachev
                        -
                        security
                        A
                        license
                        -
                        quality
                        An MCP server that enables AI assistants to manage infrastructure, applications, databases, and services through the Coolify PaaS platform.
                        Last updated -
                        2
                        1
                        MIT License

                      View all related MCP servers

                      New MCP Servers

                      MCP directory API

                      We provide all the information about MCP servers via our MCP API.

                      curl -X GET 'https://glama.ai/api/mcp/v1/servers/GoCoder7/coolify-mcp-server'

                      If you have feedback or need assistance with the MCP directory API, please join our Discord server