Skip to main content
Glama

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

Related MCP server: Coolify MCP Server

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

  1. "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

  2. "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

  3. 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

Available Tools

18 tools
create_applicationC

Create a new application

Inputs: name (required), git_branch, description, git_repository.

create_databaseC

Create a new database

Inputs: name (required), type (required).

create_projectB

Create a new project

Inputs: name (required), description.

create_serverC

Create a new server

Inputs: ip (required), name (required), port, user.

deploy_applicationC

Deploy an application

Inputs: id (required), tag.

get_applicationA

Get details of a specific application

Inputs: id (required).

get_versionA

Get Coolify version information

Inputs: no named parameters.

list_applicationsA

List all applications in Coolify

Inputs: no named parameters.

list_databasesA

List all databases in Coolify

Inputs: no named parameters.

list_projectsA

List all projects in Coolify

Inputs: no named parameters.

list_serversA

List all servers in Coolify

Inputs: no named parameters.

list_servicesA

List all services in Coolify

Inputs: no named parameters.

restart_applicationC

Restart an application

Inputs: id (required).

start_applicationC

Start an application

Inputs: id (required).

start_serviceC

Start a service

Inputs: id (required).

stop_applicationC

Stop an application

Inputs: id (required).

stop_serviceC

Stop a service

Inputs: id (required).

validate_serverC

Validate server connection

Inputs: id (required).

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3/5.0

    Scored across 18 tools

    Disambiguation4/5

    Most tools are clearly separated by resource type and action, such as list_applications vs list_databases. The only slight ambiguity is start_application vs deploy_application, which have related but not identical purposes.

    Naming Consistency5/5

    All tools use a consistent verb_noun snake_case pattern, e.g., list_applications, create_database, validate_server, get_version. There are no mixed conventions or vague generic names.

    Tool Count4/5

    18 tools is slightly above the typical sweet spot but reasonable given the server covers applications, databases, servers, projects, services, and version info. Each tool corresponds to a concrete operation, so the count feels justified rather than bloated.

    Completeness2/5

    Application lifecycle coverage is fairly strong with create, get, list, start, stop, restart, and deploy, but update and delete are missing. Other resources are much thinner: databases only support list/create, servers list/create/validate, projects list/create, and services list/start/stop, leaving obvious gaps for a management tool.

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      A powerful Model Context Protocol server that enables AI assistants to manage Coolify infrastructure through natural language, supporting application deployment, database management, resource monitoring, and DevOps automation.
      19
      MIT
    • A
      license
      B
      quality
      D
      maintenance
      Enables AI assistants to interact with Coolify for complete infrastructure management including applications, databases, servers, deployments, and team operations. Provides 100% API coverage with 64 tools for managing the entire Coolify ecosystem through natural language.
      18
      11 npm
      6
      MIT
    • A
      license
      B
      quality
      C
      maintenance
      Enables control and management of Coolify self-hosted PaaS instances, allowing you to deploy applications, manage databases, monitor servers, and execute operations directly from AI assistants.
      89
      18 npm
      28
      MIT