Coolify MCP Server

Coolify MCP Server

A robust TypeScript MCP (Model Context Protocol) server for integrating with Coolify, the self-hostable alternative to Netlify and Vercel.

Features

• Complete Coolify API Integration: Manage applications, databases, servers, projects, and services
• Type-Safe: Full TypeScript support with comprehensive type definitions
• MCP Protocol: Compatible with Claude and other MCP clients
• Resource Access: Expose Coolify resources through MCP resource endpoints
• Tool Support: Comprehensive set of tools for Coolify operations

Installation

npm install
npm run build

Configuration

Environment Variables

The server requires environment variables to connect to your Coolify instance:

export COOLIFY_API_URL="http://localhost:8000"
export COOLIFY_API_TOKEN="your-api-token-here"
export COOLIFY_TEAM_ID="optional-team-id"  # Optional

Or create a .env file:

COOLIFY_API_URL=http://localhost:8000
COOLIFY_API_TOKEN=your-api-token-here
COOLIFY_TEAM_ID=optional-team-id

MCP Client Configuration

Claude Desktop

Add the server to your Claude Desktop configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "coolify": {
      "command": "node",
      "args": ["/path/to/coolify-mcp-server/dist/index.js"],
      "env": {
        "COOLIFY_API_URL": "http://localhost:8000",
        "COOLIFY_API_TOKEN": "your-api-token-here",
        "COOLIFY_TEAM_ID": "optional-team-id"
      }
    }
  }
}

Alternative: NPX Usage

If you publish to npm, users can run via npx:

{
  "mcpServers": {
    "coolify": {
      "command": "npx",
      "args": ["@joshuarileydev/coolify-mcp-server", "--yes"],
      "env": {
        "COOLIFY_API_URL": "http://localhost:8000",
        "COOLIFY_API_TOKEN": "your-api-token-here",
        "COOLIFY_TEAM_ID": "optional-team-id"
      }
    }
  }
}

Or use the executable name directly:

{
  "mcpServers": {
    "coolify": {
      "command": "npx",
      "args": ["coolify-mcp-server", "--yes"],
      "env": {
        "COOLIFY_API_URL": "http://localhost:8000",
        "COOLIFY_API_TOKEN": "your-api-token-here",
        "COOLIFY_TEAM_ID": "optional-team-id"
      }
    }
  }
}

Development Setup

For development, you can use the TypeScript source directly:

{
  "mcpServers": {
    "coolify": {
      "command": "npx",
      "args": ["tsx", "/path/to/coolify-mcp-server/src/index.ts"],
      "env": {
        "COOLIFY_API_URL": "http://localhost:8000",
        "COOLIFY_API_TOKEN": "your-api-token-here",
        "COOLIFY_TEAM_ID": "optional-team-id"
      }
    }
  }
}

Other MCP Clients

For other MCP clients that support environment variables, ensure the following variables are set:

• COOLIFY_API_URL (required)
• COOLIFY_API_TOKEN (required)
• COOLIFY_TEAM_ID (optional)

Example shell script:

#!/bin/bash
export COOLIFY_API_URL="http://localhost:8000"
export COOLIFY_API_TOKEN="your-api-token-here"
export COOLIFY_TEAM_ID="your-team-id"

node /path/to/coolify-mcp-server/dist/index.js

Available Tools

Applications

• list_applications - List all applications
• get_application - Get application details
• create_application - Create new application
• start_application - Start an application
• stop_application - Stop an application
• restart_application - Restart an application
• deploy_application - Deploy an application

Databases

• list_databases - List all databases
• create_database - Create new database

Servers

• list_servers - List all servers
• create_server - Create new server
• validate_server - Validate server connection

Projects

• list_projects - List all projects
• create_project - Create new project

Services

• list_services - List all services
• start_service - Start a service
• stop_service - Stop a service

System

• get_version - Get Coolify version

Available Resources

The server exposes these MCP resources:

• coolify://applications - All applications
• coolify://databases - All databases
• coolify://servers - All servers
• coolify://projects - All projects
• coolify://services - All services
• coolify://teams - All teams

API Token Setup

1. Log into your Coolify instance
2. Navigate to "Keys & Tokens" > "API tokens"
3. Click "Create New Token"
4. Choose appropriate permissions:
   • read-only: Read data only
   • read:sensitive: Read with sensitive data
   • *: Full access (recommended for MCP server)
5. Copy the generated token

Security Note

When using the MCP server with Claude Desktop or other clients, your API token will be stored in the configuration file. Ensure this file has appropriate permissions:

# macOS/Linux
chmod 600 ~/Library/Application\ Support/Claude/claude_desktop_conf