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

Log into your Coolify instance
Navigate to "Keys & Tokens" > "API tokens"
Click "Create New Token"
Choose appropriate permissions:
- read-only: Read data only
- read:sensitive: Read with sensitive data
- *: Full access (recommended for MCP server)
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_config.json

# Or set environment variables in your shell profile instead
echo 'export COOLIFY_API_TOKEN="your-token-here"' >> ~/.bashrc

Development

# Install dependencies
npm install

# Run in development mode (requires env vars)
COOLIFY_API_URL=http://localhost:8000 COOLIFY_API_TOKEN=your-token npm run dev

# Build for production
npm run build

# Run built version
npm start

# Lint code
npm run lint

# Type check
npm run typecheck

Troubleshooting

Common Issues

"COOLIFY_API_URL and COOLIFY_API_TOKEN environment variables are required"
- Ensure environment variables are set before starting the server
- Check that your .env file is in the correct location
- Verify variable names are spelled correctly
"Tool execution failed: Request failed"
- Verify your Coolify instance is running and accessible
- Check that the API URL is correct (include protocol: http:// or https://)
- Ensure your API token has the necessary permissions
MCP server not appearing in Claude Desktop
- Restart Claude Desktop after updating configuration
- Check the configuration file path is correct for your OS
- Verify JSON syntax in the configuration file

Debug Mode

To see detailed error messages, run the server with debug output:

DEBUG=* node dist/index.js

License

MIT