Coolify MCP Server

How to use

Install and run the MCP server as described below, then connect your MCP client to the provided stdio configurations. You can operate and orchestrate Coolify resources using the available tools and resource endpoints. Use the client to list, create, start, stop, deploy, and manage resources such as applications, databases, servers, projects, and services. The server is designed to be compatible with MCP clients like Claude Desktop, enabling you to manage Coolify resources directly from your preferred interface.

How to install

Prerequisites: ensure Node.js and npm are installed on your machine. You will also need access to a running Coolify instance and an API token with appropriate permissions.

npm install
npm run build

Configuration and usage notes

Set up the environment variables to connect to your Coolify instance. These variables are required for the MCP server to authenticate and access resources.

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

Or create a .env file with the same keys.

Configure your MCP client to run the Coolify MCP server as a stdio process. The following configurations show practical ways to start the server from your MCP client environment.

Available MCP configurations (stdio)

{
  "mcpServers": {
    "coolify": {
      "type": "stdio",
      "name": "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"
      }
    }
  }
}
```

```json
{
  "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"
      }
    }
  }
}
```

```json
{
  "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"
      }
    }
  }
}
```

```json
{
  "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"
      }
    }
  }
}
```

Note: Each configuration includes the necessary environment variables and points to how to start the server from your MCP client environment. You can choose the approach that matches your workflow, whether you prefer running the server via node, npx, or directly from TypeScript during development.

If you need to export environment variables in a shell session, you can set them as shown and then start the server with your chosen method.

Available tools and endpoints

The server provides a comprehensive set of tools to manage Coolify resources. You can list, create, start, stop, and deploy resources across applications, databases, servers, projects, and services. The core tools include:

• 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
• list_databases — List all databases
• create_database — Create new database
• list_servers — List all servers
• create_server — Create new server
• validate_server — Validate server connection
• list_projects — List all projects
• create_project — Create new project
• list_services — List all services
• start_service — Start a service
• stop_service — Stop a service
• get_version — Get Coolify version

These tools map to MCP resource endpoints that expose data for applications, databases, servers, projects, and services. You can use the tools to manage lifecycle operations and retrieve version information about the Coolify instance.

Available resources

The server exposes MCP resource endpoints to access Coolify data programmatically. Resources include applications, databases, servers, projects, services, and teams. You can query these endpoints to list resources, fetch details, and drive workflows across your Coolify environment.

Security and tokens

Your MCP server relies on a valid API token to authenticate with Coolify. Ensure your token has the appropriate permissions for read or full access, depending on your use case. Store tokens securely in your MCP client configuration.

Development

Development steps include installing dependencies, building, and running in development mode. Use the following commands to work with the project locally.

# 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 tips cover common issues such as missing environment variables, incorrect API URLs, or token permissions. If the server does not appear in your MCP client, restart the client after updating configurations and verify the JSON syntax of your config files.

Troubleshooting

Common issues and steps to resolve them include:

• Ensure COOLIFY_API_URL and COOLIFY_API_TOKEN are set before starting the server
• Verify the API URL includes http:// or https://
• Check that your API token has the necessary permissions
• Restart your MCP client after updating configuration
• Validate JSON syntax in the configuration file

Development and debugging

For debugging, you can enable verbose logs to see detailed error messages. Run the server with debug output to diagnose problems.

DEBUG=* node dist/index.js

Security note

Store API tokens securely within your MCP client configuration. Use secure file permissions on your local machine to prevent unauthorized access to sensitive tokens.

list_applications

List all applications in your Coolify projects

get_application

Retrieve details for a specific application

create_application

Create a new application under a project or environment

start_application

Start an application instance

stop_application

Stop a running application

restart_application

Restart an application

deploy_application

Deploy an application to its target environment

list_databases

List all databases available to your Coolify account

create_database

Create a new database instance

list_servers

List all servers configured in Coolify

create_server

Create a new server entry

validate_server

Validate server connection credentials and reachability

list_projects

List all projects in your Coolify workspace

create_project

Create a new project in your Coolify workspace

list_services

List all services running within Coolify resources

start_service

Start a stopped service

stop_service

Stop a running service

get_version

Get the Coolify version information