### Coolify CLI Development Setup

Source: https://github.com/stumason/coolify-mcp/blob/main/README.md

Instructions for cloning the repository, installing dependencies, building, testing, and running the Coolify CLI locally.

```bash
# Clone and install
git clone https://github.com/stumason/coolify-mcp.git
cd coolify-mcp
npm install

# Build
npm run build

# Test
npm test

# Run locally
COOLIFY_BASE_URL="https://your-coolify.com" \
COOLIFY_ACCESS_TOKEN="your-token" \
node dist/index.js
```

--------------------------------

### Installation & Server Startup

Source: https://context7.com/stumason/coolify-mcp/llms.txt

Instructions on how to install and start the Coolify MCP Server using different methods, including Claude Desktop, Claude Code CLI, and programmatic startup.

```APIDOC
## Installation & Server Startup

Registers the server with Claude Desktop or Claude Code so AI tools can call it.

```jsonc
// Claude Desktop: ~/Library/Application Support/Claude/claude_desktop_config.json
{
  "mcpServers": {
    "coolify": {
      "command": "npx",
      "args": ["-y", "@masonator/coolify-mcp"],
      "env": {
        "COOLIFY_ACCESS_TOKEN": "your-api-token",
        "COOLIFY_BASE_URL": "https://coolify.example.com"
      }
    }
  }
}
```

```bash
# Claude Code CLI
claude mcp add coolify \
  -e COOLIFY_BASE_URL="https://coolify.example.com" \
  -e COOLIFY_ACCESS_TOKEN="your-api-token" \
  -- npx @masonator/coolify-mcp@latest

# With Cloudflare Zero Trust headers
npx @masonator/coolify-mcp \
  --header "CF-Access-Client-Id: abc123.access" \
  --header "CF-Access-Client-Secret: secret"
```

```typescript
// Programmatic startup (e.g. in tests)
import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
import { CoolifyMcpServer } from './src/lib/mcp-server.js';

const server = new CoolifyMcpServer({
  baseUrl: 'https://coolify.example.com',
  accessToken: 'tok-xxxx',
  customHeaders: { 'CF-Access-Client-Id': 'abc.access' }, // optional
});
await server.connect(new StdioServerTransport());
```
```

--------------------------------

### Install and Build Project Dependencies

Source: https://github.com/stumason/coolify-mcp/blob/main/CLAUDE.md

Standard npm commands for installing dependencies, building the project, running tests, linting, and formatting.

```bash
npm install          # Install dependencies
npm run build        # Build TypeScript to dist/
npm test             # Run all tests
npm run lint         # Run ESLint
npm run format       # Run Prettier
```

--------------------------------

### Get coolify-mcp Server Version

Source: https://github.com/stumason/coolify-mcp/blob/main/README.md

Verify the installed version of the coolify-mcp server.

```text
get_mcp_version
```

--------------------------------

### Get Help and Documentation

Source: https://github.com/stumason/coolify-mcp/blob/main/README.md

Access documentation and search for solutions to common issues.

```text
How do I set up Docker Compose with Coolify?
```

```text
Search the docs for health check configuration
```

```text
How do I fix a 502 Bad Gateway error?
```

```text
What are Coolify environment variables?
```

--------------------------------

### Manage Environments

Source: https://github.com/stumason/coolify-mcp/blob/main/README.md

Perform actions such as listing, getting, creating, or deleting environments.

```text
environments
```

--------------------------------

### Control Application Lifecycle

Source: https://github.com/stumason/coolify-mcp/blob/main/README.md

Start, stop, or restart applications.

```text
control
```

--------------------------------

### Manage Projects

Source: https://github.com/stumason/coolify-mcp/blob/main/README.md

Perform actions such as listing, getting, creating, updating, or deleting projects.

```text
projects
```

--------------------------------

### Get Infrastructure Overview

Source: https://github.com/stumason/coolify-mcp/blob/main/README.md

Obtain a high-level summary of all infrastructure components, including servers, projects, applications, databases, and services.

```text
get_infrastructure_overview
```

--------------------------------

### `get_infrastructure_overview` Tool

Source: https://context7.com/stumason/coolify-mcp/llms.txt

This tool returns counts and compact summaries for every resource type in a single call, serving as a recommended starting point for AI assistants.

```APIDOC
## `get_infrastructure_overview` Tool

Returns counts and compact summaries for every resource type in one call. The recommended starting point for any session.

```typescript
// MCP tool invocation (as an AI assistant would call it)
// tool: "get_infrastructure_overview"
// args: {}

// Expected response shape:
{
  "data": {
    "summary": {
      "servers": 2,
      "projects": 5,
      "applications": 21,
      "databases": 8,
      "services": 4
    },
    "servers": [{ "uuid": "srv1", "name": "vps-01", "ip": "1.2.3.4", "is_reachable": true }],
    "projects": [{ "uuid": "proj1", "name": "my-saas", "description": "Main product" }],
    "applications": [{ "uuid": "app1", "name": "api", "status": "running:healthy", "fqdn": "api.example.com" }],
    "databases": [{ "uuid": "db1", "name": "prod-pg", "type": "postgresql", "status": "running", "is_public": false }],
    "services": [{ "uuid": "svc1", "name": "redis", "type": "redis", "status": "running" }]
  }
}
```
```

--------------------------------

### Get Application Logs

Source: https://github.com/stumason/coolify-mcp/blob/main/README.md

Retrieve the logs for a specific application.

```text
application_logs
```

--------------------------------

### Get Application Details

Source: https://github.com/stumason/coolify-mcp/blob/main/README.md

Fetch detailed information about a specific application.

```text
get_application
```

--------------------------------

### Control Service Start

Source: https://context7.com/stumason/coolify-mcp/llms.txt

Starts a service identified by its UUID. This tool can also be used to stop or restart applications and databases.

```typescript
// Start a service
// tool: "control"
{ "resource": "service", "action": "start", "uuid": "svc1" }
```

--------------------------------

### Control Tool

Source: https://context7.com/stumason/coolify-mcp/llms.txt

Starts, stops, or restarts applications, databases, or services. Returns HATEOAS `_actions` with suggested follow-up calls.

```APIDOC
## `control` Tool

Start, stop, or restart any application, database, or service. Returns HATEOAS `_actions` with suggested follow-up calls.

### Restart Application
```json
{ "tool": "control", "args": { "resource": "application", "action": "restart", "uuid": "app1" } }
```

### Stop Database
```json
{ "tool": "control", "args": { "resource": "database", "action": "stop", "uuid": "db1" } }
```

### Start Service
```json
{ "tool": "control", "args": { "resource": "service", "action": "start", "uuid": "svc1" } }
```

#### Response Example (with _actions)
```json
{
  "data": { "message": "Application restarted." },
  "_actions": [
    { "tool": "application_logs", "args": { "uuid": "app1" }, "hint": "View logs" },
    { "tool": "get_application",  "args": { "uuid": "app1" }, "hint": "Check status" },
    { "tool": "control", "args": { "resource": "application", "action": "stop", "uuid": "app1" }, "hint": "Stop" }
  ]
}
```
```

--------------------------------

### Get Server Details

Source: https://github.com/stumason/coolify-mcp/blob/main/README.md

Fetch detailed information about a specific server.

```text
get_server
```

--------------------------------

### MCP Tool Invocation: get_infrastructure_overview

Source: https://context7.com/stumason/coolify-mcp/llms.txt

Example of an AI assistant invoking the `get_infrastructure_overview` MCP tool to retrieve aggregated resource counts and summaries.

```typescript
// MCP tool invocation (as an AI assistant would call it)
// tool: "get_infrastructure_overview"
// args: {}

// Expected response shape:
{
  "data": {
    "summary": {
      "servers": 2,
      "projects": 5,
      "applications": 21,
      "databases": 8,
      "services": 4
    },
    "servers": [{ "uuid": "srv1", "name": "vps-01", "ip": "1.2.3.4", "is_reachable": true }],
    "projects": [{ "uuid": "proj1", "name": "my-saas", "description": "Main product" }],
    "applications": [{ "uuid": "app1", "name": "api", "status": "running:healthy", "fqdn": "api.example.com" }],
    "databases": [{ "uuid": "db1", "name": "prod-pg", "type": "postgresql", "status": "running", "is_public": false }],
    "services": [{ "uuid": "svc1", "name": "redis", "type": "redis", "status": "running" }]
  }
}
```

--------------------------------

### Get Server Domains

Source: https://github.com/stumason/coolify-mcp/blob/main/README.md

List all domains configured on a specific server.

```text
server_domains
```

--------------------------------

### Get Server Resources

Source: https://github.com/stumason/coolify-mcp/blob/main/README.md

View the resources currently running on a specific server.

```text
server_resources
```

--------------------------------

### Example of HATEOAS-style Response Actions

Source: https://github.com/stumason/coolify-mcp/blob/main/README.md

Responses from the MCP server include contextual `_actions` and `_pagination` fields. These suggest relevant next steps and pagination details, helping AI assistants navigate the API efficiently.

```json
{
  "data": { "uuid": "abc123", "status": "running" },
  "_actions": [
    { "tool": "application_logs", "args": { "uuid": "abc123" }, "hint": "View logs" },
    {
      "tool": "control",
      "args": { "resource": "application", "action": "restart", "uuid": "abc123" },
      "hint": "Restart"
    }
  ],
  "_pagination": { "next": { "tool": "list_applications", "args": { "page": 2 } } }
}
```

--------------------------------

### Get Database Details

Source: https://github.com/stumason/coolify-mcp/blob/main/README.md

Fetch detailed information about a specific database.

```text
get_database
```

--------------------------------

### Manage Application Lifecycle

Source: https://github.com/stumason/coolify-mcp/blob/main/README.md

Control the lifecycle of your applications, including restarting, stopping, starting, and deploying. Supports force rebuilds.

```text
Restart application {uuid}
```

```text
Stop the database {uuid}
```

```text
Start service {uuid}
```

```text
Deploy application {uuid} with force rebuild
```

--------------------------------

### Get Service Details

Source: https://github.com/stumason/coolify-mcp/blob/main/README.md

Fetch detailed information about a specific service.

```text
get_service
```

--------------------------------

### Manage Project Environments

Source: https://context7.com/stumason/coolify-mcp/llms.txt

Consolidated CRUD operations for project environments. The `get` action includes database instances omitted by the standard API.

```typescript
// List environments in a project
// tool: "environments"  args: { action: "list", project_uuid: "proj1" }
```

```typescript
// Get full environment (includes missing DB types)
// tool: "environments"  args: { action: "get", project_uuid: "proj1", name: "production" }
// => includes `dragonflys`, `keydbs`, `clickhouses` arrays if present
```

```typescript
// Create environment
// tool: "environments"  args: { action: "create", project_uuid: "proj1", name: "staging" }
```

```typescript
// Delete environment
// tool: "environments"  args: { action: "delete", project_uuid: "proj1", name: "staging" }
```

--------------------------------

### Diagnose Application Status

Source: https://github.com/stumason/coolify-mcp/blob/main/README.md

Use this command to get detailed diagnostics for a specific application, including its status, logs, environment variables, and deployment history. Accepts UUID, name, or domain.

```text
Diagnose my stuartmason.co.uk app
```

```text
What's wrong with my-api application?
```

```text
Get the logs for application {uuid}
```

```text
What environment variables are set for application {uuid}?
```

```text
Show me recent deployments for application {uuid}
```

--------------------------------

### Get Deployment Details

Source: https://context7.com/stumason/coolify-mcp/llms.txt

Retrieves detailed information about a specific deployment, with an option to include log lines. Logs are excluded by default.

```typescript
// Get deployment details (no logs)
// tool: "deployment"
{ "action": "get", "uuid": "dep1" }
```

```typescript
// Get deployment with last 50 log lines (page 1 = most recent)
// tool: "deployment"
{ "action": "get", "uuid": "dep1", "lines": 50, "page": 1 }
```

--------------------------------

### Add New Coolify API Client Method

Source: https://github.com/stumason/coolify-mcp/blob/main/CLAUDE.md

Example of adding a new client method to interact with a Coolify API endpoint. Ensure explicit return types are used.

```typescript
async getResource(uuid: string): Promise<Resource> {
  return this.request<Resource>(`/resources/${uuid}`);
}
```

--------------------------------

### Paginate List Endpoints in Coolify MCP

Source: https://github.com/stumason/coolify-mcp/blob/main/README.md

For large deployments, list endpoints support optional pagination. This example shows how to request page 2 with 10 items per page.

```bash
# Get page 2 with 10 items per page
list_applications(page=2, per_page=10)
```

--------------------------------

### Test New Client Method in MCP Server

Source: https://github.com/stumason/coolify-mcp/blob/main/CLAUDE.md

Example of adding a mocked test for a new client method in the MCP server tests. This ensures the client method is called correctly.

```typescript
it('should call client method', async () => {
  const spy = jest.spyOn(server['client'], 'getResource').mockResolvedValue({ uuid: 'test' });
  await server.get_resource('test-uuid');
  expect(spy).toHaveBeenCalledWith('test-uuid');
});
```

--------------------------------

### Create Project Environment

Source: https://github.com/stumason/coolify-mcp/blob/main/README.md

Set up a new environment for an existing project.

```text
Create a staging environment in project {uuid}
```

--------------------------------

### Create New Project

Source: https://github.com/stumason/coolify-mcp/blob/main/README.md

Initialize a new project within your Coolify instance.

```text
Create a new project called "my-app"
```

--------------------------------

### Initialize and Search DocsSearchEngine

Source: https://context7.com/stumason/coolify-mcp/llms.txt

Initializes the DocsSearchEngine, which lazily loads and indexes Coolify documentation. The first search call may take time due to fetching and indexing. Subsequent calls use the in-memory index. Use this to search documentation programmatically.

```typescript
import { DocsSearchEngine, parseDocs } from './src/lib/docs-search.js';

const engine = new DocsSearchEngine();

// First call fetches + indexes docs (15s timeout); subsequent calls use in-memory index
const results = await engine.search('docker compose environment variables', 5);
// => [{ title: "Docker Compose > Environment Variables", url: "...", snippet: "...", score: 12.4 }]
```

--------------------------------

### Manage Applications

Source: https://github.com/stumason/coolify-mcp/blob/main/README.md

Create, update, or delete applications. Supports deployment from public repos, private GitHub, SSH keys, or Docker images. Also allows configuration of health checks.

```text
application
```

--------------------------------

### Get Coolify API Version

Source: https://github.com/stumason/coolify-mcp/blob/main/README.md

Retrieve the version of the Coolify API.

```text
get_version
```

--------------------------------

### Create Public Application

Source: https://context7.com/stumason/coolify-mcp/llms.txt

Deploys an application from a public Git repository. Requires project and server UUIDs, Git repository URL, branch, build pack, exposed ports, and optionally FQDN and instant deploy flag.

```typescript
// Deploy from a public Git repository
// tool: "application"
{
  "action": "create_public",
  "project_uuid": "proj1",
  "server_uuid": "srv1",
  "git_repository": "https://github.com/org/repo",
  "git_branch": "main",
  "build_pack": "nixpacks",
  "ports_exposes": "3000",
  "fqdn": "app.example.com",
  "instant_deploy": true
}
// => { "data": { "uuid": "app-new-uuid" } }
```

--------------------------------

### Programmatic Coolify MCP Server Startup

Source: https://context7.com/stumason/coolify-mcp/llms.txt

Initialize and connect the Coolify MCP server programmatically using TypeScript, suitable for testing or custom integrations.

```typescript
// Programmatic startup (e.g. in tests)
import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
import { CoolifyMcpServer } from './src/lib/mcp-server.js';

const server = new CoolifyMcpServer({
  baseUrl: 'https://coolify.example.com',
  accessToken: 'tok-xxxx',
  customHeaders: { 'CF-Access-Client-Id': 'abc.access' }, // optional
});
await server.connect(new StdioServerTransport());
```

--------------------------------

### List Applications

Source: https://github.com/stumason/coolify-mcp/blob/main/README.md

Retrieve a summary list of all applications.

```text
list_applications
```

--------------------------------

### Get Current Authenticated Team

Source: https://context7.com/stumason/coolify-mcp/llms.txt

Retrieves information about the currently authenticated team. This is a read-only operation.

```typescript
// Get current authenticated team
// tool: "teams"
{ "action": "get_current" }
// => { "data": { "id": 1, "name": "My Team", "description": "Default team" } }
```

--------------------------------

### Control Database Stop

Source: https://context7.com/stumason/coolify-mcp/llms.txt

Stops a database identified by its UUID. This tool can also be used to start or restart services.

```typescript
// Stop a database
// tool: "control"
{ "resource": "database", "action": "stop", "uuid": "db1" }
```

--------------------------------

### Manage Databases

Source: https://github.com/stumason/coolify-mcp/blob/main/README.md

Create or delete databases of various types including PostgreSQL, MySQL, MongoDB, Redis, and more.

```text
database
```

--------------------------------

### Get Members of a Specific Team

Source: https://context7.com/stumason/coolify-mcp/llms.txt

Retrieves a list of members for a specific team identified by its ID. This is a read-only operation.

```typescript
// Get members of a specific team by id
// tool: "teams"
{ "action": "get_members", "id": 2 }
```

--------------------------------

### Get Members of Current Team

Source: https://context7.com/stumason/coolify-mcp/llms.txt

Retrieves a list of members belonging to the current authenticated team. This is a read-only operation.

```typescript
// Get members of the current team
// tool: "teams"
{ "action": "get_current_members" }
// => { "data": [{ "id": 1, "name": "Stu Mason", "email": "stu@example.com" }] }
```

--------------------------------

### Manage Application Environment Variables

Source: https://github.com/stumason/coolify-mcp/blob/main/README.md

List, create, update, or delete environment variables for applications.

```text
env_vars
```

--------------------------------

### Claude Code CLI Server Startup

Source: https://context7.com/stumason/coolify-mcp/llms.txt

Add and configure the Coolify MCP server using the Claude Code CLI, including environment variables and custom headers.

```bash
# Claude Code CLI
claude mcp add coolify \
  -e COOLIFY_BASE_URL="https://coolify.example.com" \
  -e COOLIFY_ACCESS_TOKEN="your-api-token" \
  -- npx @masonator/coolify-mcp@latest
```

```bash
# With Cloudflare Zero Trust headers
npx @masonator/coolify-mcp \
  --header "CF-Access-Client-Id: abc123.access" \
  --header "CF-Access-Client-Secret: secret"
```

--------------------------------

### Get Specific GitHub App Details

Source: https://context7.com/stumason/coolify-mcp/llms.txt

Fetches comprehensive details for a particular GitHub App using its integer ID.

```typescript
// Get full details for a specific app
// tool: "github_apps"
{ "action": "get", "id": 42 }
```

--------------------------------

### Deploy Application from Repository

Source: https://github.com/stumason/coolify-mcp/blob/main/README.md

Deploy applications from various sources, including private GitHub repositories, public repositories, and Docker Hub.

```text
Deploy my app from private GitHub repo org/repo on branch main
```

```text
Deploy nginx:latest from Docker Hub
```

```text
Deploy from public repo https://github.com/org/repo
```

--------------------------------

### Create Application from Docker Image

Source: https://context7.com/stumason/coolify-mcp/llms.txt

Deploys an application using a Docker image. Requires project and server UUIDs, Docker image name and tag, exposed ports, and optionally domains.

```typescript
// Deploy a Docker image
// tool: "application"
{
  "action": "create_dockerimage",
  "project_uuid": "proj1",
  "server_uuid": "srv1",
  "docker_registry_image_name": "nginx",
  "docker_registry_image_tag": "1.25-alpine",
  "ports_exposes": "80",
  "domains": "static.example.com"
}
```

--------------------------------

### Run MCP Server Locally

Source: https://github.com/stumason/coolify-mcp/blob/main/CLAUDE.md

Environment variables required to run the MCP server locally. Ensure COOLIFY_BASE_URL and COOLIFY_ACCESS_TOKEN are set.

```bash
COOLIFY_BASE_URL="https://your-coolify.com" COOLIFY_ACCESS_TOKEN="token" node dist/index.js
```

--------------------------------

### Get DocsSearchEngine Chunk Count

Source: https://context7.com/stumason/coolify-mcp/llms.txt

Retrieves the approximate number of chunks the DocsSearchEngine has indexed. This is useful for understanding the scale of the indexed documentation.

```typescript
engine.getChunkCount(); // => 1543 (approximate)
```

--------------------------------

### Run Tests Command

Source: https://github.com/stumason/coolify-mcp/blob/main/CONTRIBUTING.md

Execute this command to run all project tests.

```bash
npm test
```

--------------------------------

### Run Coolify MCP Server with Cursor

Source: https://github.com/stumason/coolify-mcp/blob/main/README.md

Execute this command to run the Coolify MCP server when using Cursor. It sets environment variables for authentication and base URL before launching the MCP server.

```bash
env COOLIFY_ACCESS_TOKEN=your-api-token COOLIFY_BASE_URL=https://your-coolify-instance.com npx -y @masonator/coolify-mcp
```

--------------------------------

### Deploy One-Click Service

Source: https://context7.com/stumason/coolify-mcp/llms.txt

Creates a new instance of a pre-packaged one-click service on a specified server and project.

```typescript
// Deploy a pre-packaged one-click service
// tool: "service"
{
  "action": "create",
  "server_uuid": "srv1",
  "project_uuid": "proj1",
  "type": "pocketbase",
  "name": "my-pocketbase",
  "environment_name": "production",
  "instant_deploy": true
}
```

--------------------------------

### CoolifyClient HTTP Client Initialization

Source: https://context7.com/stumason/coolify-mcp/llms.txt

Instantiate the CoolifyClient for direct interaction with the Coolify REST API. Ensure connection validation on startup.

```typescript
import { CoolifyClient } from './src/lib/coolify-client.js';

const client = new CoolifyClient({
  baseUrl: 'https://coolify.example.com',
  accessToken: 'tok-xxxx',
});

// Validate connectivity on startup
await client.validateConnection(); // throws if unreachable
```

--------------------------------

### Claude Desktop Configuration for Coolify MCP Server

Source: https://context7.com/stumason/coolify-mcp/llms.txt

Configure Claude Desktop to connect to the Coolify MCP server by specifying the command, arguments, and environment variables.

```jsonc
// Claude Desktop: ~/Library/Application Support/Claude/claude_desktop_config.json
{
  "mcpServers": {
    "coolify": {
      "command": "npx",
      "args": ["-y", "@masonator/coolify-mcp"],
      "env": {
        "COOLIFY_ACCESS_TOKEN": "your-api-token",
        "COOLIFY_BASE_URL": "https://coolify.example.com"
      }
    }
  }
}
```

--------------------------------

### Manage Services

Source: https://github.com/stumason/coolify-mcp/blob/main/README.md

Create, update, or delete services.

```text
service
```

--------------------------------

### Project Directory Structure

Source: https://github.com/stumason/coolify-mcp/blob/main/CONTRIBUTING.md

Overview of the project's directory structure, highlighting key components.

```text
src/
  index.ts              # Entry point
  lib/
    coolify-client.ts # HTTP client for Coolify API
    mcp-server.ts     # MCP server with tool definitions
  types/
    coolify.ts        # TypeScript types
  __tests__/            # Jest tests

```

--------------------------------

### Manage Database Backups

Source: https://github.com/stumason/coolify-mcp/blob/main/README.md

Configure and manage backup schedules, retention policies, S3 storage, and view backup execution history.

```text
database_backups
```

--------------------------------

### deployment Tool

Source: https://context7.com/stumason/coolify-mcp/llms.txt

Fetches deployment details, cancels deployments, or lists deployments for an application.

```APIDOC
## `deployment` Tool — Get / Cancel / List for App

Fetches deployment details with optional paginated log output, cancels in-progress deployments, or lists all deployments for a specific application. Logs are excluded by default to conserve tokens.

### Get Deployment Details

**Description**: Fetches details for a specific deployment, optionally including logs.

**Tool**: `deployment`

**Action**: `get`

**Parameters**:
- **uuid** (string) - Required - The UUID of the deployment.
- **lines** (integer) - Optional - The number of log lines to retrieve.
- **page** (integer) - Optional - The page number for log retrieval (1 is most recent).

**Response Example (No Logs)**:
```json
{
  "data": {
    "uuid": "dep1",
    "status": "finished",
    "commit": "abc1234",
    "logs_available": true,
    "logs_info": "Logs available (45231 chars). Use lines param to retrieve."
  }
}
```

**Response Example (With Logs)**:
```json
{
  "data": {
    "uuid": "dep1",
    "status": "finished",
    "commit": "abc1234",
    "logs_available": true,
    "logs_info": "Logs available (45231 chars). Use lines param to retrieve."
  },
  "_pagination": {
    "next": "..."
  }
}
```

### List Deployments for Application

**Description**: Lists all deployments for a specific application.

**Tool**: `deployment`

**Action**: `list_for_app`

**Parameters**:
- **uuid** (string) - Required - The UUID of the application.

**Response Example**:
```json
{
  "data": {
    "count": 35,
    "deployments": [...] 
  }
}
```

### Cancel Deployment

**Description**: Cancels an in-progress deployment.

**Tool**: `deployment`

**Action**: `cancel`

**Parameters**:
- **uuid** (string) - Required - The UUID of the deployment to cancel.
```

--------------------------------

### List Servers

Source: https://github.com/stumason/coolify-mcp/blob/main/README.md

Retrieve a summary list of all registered servers.

```text
list_servers
```

--------------------------------

### DocsSearchEngine Class

Source: https://context7.com/stumason/coolify-mcp/llms.txt

Provides an internal BM25 search engine over Coolify documentation. It lazily loads, parses, and indexes documentation content. The `search` method allows querying the indexed documents, and `getChunkCount` returns the approximate number of indexed chunks.

```APIDOC
## `DocsSearchEngine` Class

Internal BM25 search engine over Coolify documentation. Lazy-loads `https://coolify.io/docs/llms-full.txt`, parses it into chunks at `##` section boundaries, and indexes with MiniSearch. The parsed doc format and chunk count are accessible for testing.

```typescript
import { DocsSearchEngine, parseDocs } from './src/lib/docs-search.js';

const engine = new DocsSearchEngine();

// First call fetches + indexes docs (15s timeout); subsequent calls use in-memory index
const results = await engine.search('docker compose environment variables', 5);
// => [{ title: "Docker Compose > Environment Variables", url: "...", snippet: "...", score: 12.4 }]

engine.getChunkCount(); // => 1543 (approximate)

// Low-level: parse a raw llms-full.txt string into chunks for testing
const text = "---\nurl: /docs/example\ndescription: Example page\n---\n# Example\n## Section A\nContent here.";
const chunks = parseDocs(text);
// => [{ id: 0, title: "Example > Section A", url: "https://coolify.io/docs/example", content: "Content here." }]
```
```

--------------------------------

### Publish New Version to npm

Source: https://github.com/stumason/coolify-mcp/blob/main/CLAUDE.md

Commands for versioning and publishing the project to npm. This process is automated by CI on version bumps.

```bash
npm version patch|minor|major
git push origin main --tags
```

--------------------------------

### List Deployments for an Application

Source: https://context7.com/stumason/coolify-mcp/llms.txt

Fetches a list of all deployments associated with a specific application, providing essential fields without log content.

```typescript
// List deployments for an application (essential fields, no log blobs)
// tool: "deployment"
{ "action": "list_for_app", "uuid": "app1" }
```

--------------------------------

### List Databases

Source: https://github.com/stumason/coolify-mcp/blob/main/README.md

Retrieve a summary list of all databases.

```text
list_databases
```

--------------------------------

### Add Coolify MCP Server via Claude Code CLI

Source: https://github.com/stumason/coolify-mcp/blob/main/README.md

Use this command in the Claude Code CLI to add the Coolify MCP server. It's recommended to use the `@latest` tag for reliable startup instead of the `-y` flag.

```bash
claude mcp add coolify \
  -e COOLIFY_BASE_URL="https://your-coolify-instance.com" \
  -e COOLIFY_ACCESS_TOKEN="your-api-token" \
  -- npx @masonator/coolify-mcp@latest
```

--------------------------------

### deploy Tool

Source: https://context7.com/stumason/coolify-mcp/llms.txt

Triggers a deployment by application UUID or deployment tag.

```APIDOC
## `deploy` Tool

Triggers a deployment by application UUID or by a deployment tag. Automatically detects UUID format (alphanumeric 20+ chars or standard hyphenated UUID) versus a tag string.

### Deploy Application

**Description**: Triggers a deployment for an application.

**Tool**: `deploy`

**Parameters**:
- **tag_or_uuid** (string) - Required - The tag or UUID of the application to deploy.
- **force** (boolean) - Optional - Whether to force the deployment.
```

--------------------------------

### Supported Database Types

Source: https://context7.com/stumason/coolify-mcp/llms.txt

Lists the supported database engine types for creation.

```plaintext
// Supported types: postgresql | mysql | mariadb | mongodb | redis | keydb | clickhouse | dragonfly
```

--------------------------------

### Application Tool - Create/Update/Delete

Source: https://context7.com/stumason/coolify-mcp/llms.txt

Manages applications through various creation modes (public Git, private GitHub App, Docker image), updates, and deletions. Supports instant deployment and health checks.

```APIDOC
## `application` Tool — Create / Update / Delete

Supports four creation modes plus update and delete, all on one tool.

### Create Public Git Repository
```json
{
  "action": "create_public",
  "project_uuid": "proj1",
  "server_uuid": "srv1",
  "git_repository": "https://github.com/org/repo",
  "git_branch": "main",
  "build_pack": "nixpacks",
  "ports_exposes": "3000",
  "fqdn": "app.example.com",
  "instant_deploy": true
}
```

### Create Private GitHub App
```json
{
  "action": "create_github",
  "project_uuid": "proj1",
  "server_uuid": "srv1",
  "github_app_uuid": "gh-app-1",
  "git_repository": "org/private-repo",
  "git_branch": "main",
  "health_check_enabled": true,
  "health_check_path": "/health",
  "health_check_interval": 30,
  "health_check_retries": 3
}
```

### Create Docker Image
```json
{
  "action": "create_dockerimage",
  "project_uuid": "proj1",
  "server_uuid": "srv1",
  "docker_registry_image_name": "nginx",
  "docker_registry_image_tag": "1.25-alpine",
  "ports_exposes": "80",
  "domains": "static.example.com"
}
```

### Update Application
```json
{ "action": "update", "uuid": "app1", "name": "api-v2", "fqdn": "api-v2.example.com" }
```

### Delete Application
```json
{ "action": "delete", "uuid": "app1", "delete_volumes": true }
```
```

--------------------------------

### Create Daily Database Backup with S3 Storage

Source: https://context7.com/stumason/coolify-mcp/llms.txt

Configures a daily backup schedule for a specified database, storing backups locally for 7 days and in S3 for 30 days.

```typescript
// Create a daily backup with S3 storage
// tool: "database_backups"
{
  "action": "create",
  "database_uuid": "db1",
  "frequency": "0 2 * * *",
  "enabled": true,
  "save_s3": true,
  "s3_storage_uuid": "s3-store-1",
  "database_backup_retention_days_locally": 7,
  "database_backup_retention_days_s3": 30
}
```

--------------------------------

### service Tool

Source: https://context7.com/stumason/coolify-mcp/llms.txt

Manages one-click services and custom Docker Compose stacks.

```APIDOC
## `service` Tool — One-Click Services

Creates, updates, or deletes Coolify one-click services (Pocketbase, Wordpress, Plausible, etc.) or custom Docker Compose stacks. `docker_compose_raw` is automatically base64-encoded before submission.

### Create One-Click Service

**Description**: Deploys a pre-packaged one-click service to a server.

**Tool**: `service`

**Action**: `create`

**Parameters**:
- **server_uuid** (string) - Required - The UUID of the server to deploy to.
- **project_uuid** (string) - Required - The UUID of the project.
- **type** (string) - Required - The type of one-click service (e.g., "pocketbase").
- **name** (string) - Required - The name for the service instance.
- **environment_name** (string) - Required - The environment name (e.g., "production").
- **instant_deploy** (boolean) - Optional - Whether to deploy instantly.

### Create Custom Docker Compose Service

**Description**: Deploys a custom service using raw Docker Compose YAML.

**Tool**: `service`

**Action**: `create`

**Parameters**:
- **server_uuid** (string) - Required - The UUID of the server to deploy to.
- **project_uuid** (string) - Required - The UUID of the project.
- **docker_compose_raw** (string) - Required - The raw Docker Compose YAML content (will be base64-encoded).

### Delete Service

**Description**: Deletes a service instance.

**Tool**: `service`

**Action**: `delete`

**Parameters**:
- **uuid** (string) - Required - The UUID of the service to delete.
- **delete_volumes** (boolean) - Optional - Whether to delete associated volumes.
```

--------------------------------

### List Application Environment Variables

Source: https://context7.com/stumason/coolify-mcp/llms.txt

Lists environment variables for an application in summary mode, showing UUID, key, value, and build-time status. Requires the application's UUID.

```typescript
// List env vars for an application (summary mode — uuid, key, value, is_build_time only)
// tool: "env_vars"
{ "resource": "application", "action": "list", "uuid": "app1" }
// => [{ "uuid": "env1", "key": "DATABASE_URL", "value": "postgres://...", "is_build_time": false }]
```

--------------------------------

### List Database Backup Schedules

Source: https://context7.com/stumason/coolify-mcp/llms.txt

Retrieves a list of all configured backup schedules for a given database.

```typescript
// List all backup schedules for a database
// tool: "database_backups"
{ "action": "list_schedules", "database_uuid": "db1" }
```

--------------------------------

### List All SSH Deploy Keys

Source: https://context7.com/stumason/coolify-mcp/llms.txt

Retrieves a list of all configured SSH deploy keys.

```typescript
// List all keys
// tool: "private_keys"
{ "action": "list" }
```

--------------------------------

### Configure Claude Desktop MCP Server

Source: https://github.com/stumason/coolify-mcp/blob/main/README.md

Add this configuration to your Claude Desktop's config file to enable the Coolify MCP server. Ensure you replace placeholder tokens and URLs with your actual credentials.

```json
{
  "mcpServers": {
    "coolify": {
      "command": "npx",
      "args": ["-y", "@masonator/coolify-mcp"],
      "env": {
        "COOLIFY_ACCESS_TOKEN": "your-api-token",
        "COOLIFY_BASE_URL": "https://your-coolify-instance.com"
      }
    }
  }
}
```

--------------------------------

### private_keys Tool

Source: https://context7.com/stumason/coolify-mcp/llms.txt

Manages SSH deploy keys for private repository deployments.

```APIDOC
## `private_keys` Tool

Full CRUD for SSH deploy keys used by private repository deployments.

### Create SSH Key

**Description**: Creates a new SSH deploy key.

**Tool**: `private_keys`

**Action**: `create`

**Parameters**:
- **private_key** (string) - Required - The private SSH key content.
- **name** (string) - Required - The name for the key.
- **description** (string) - Optional - A description for the key.

**Response Example**:
```json
{ "data": { "uuid": "key-uuid" } }
```

### List SSH Keys

**Description**: Lists all available SSH deploy keys.

**Tool**: `private_keys`

**Action**: `list`

### Delete SSH Key

**Description**: Deletes an SSH deploy key.

**Tool**: `private_keys`

**Action**: `delete`

**Parameters**:
- **uuid** (string) - Required - The UUID of the key to delete.
```

--------------------------------

### database_backups Tool

Source: https://context7.com/stumason/coolify-mcp/llms.txt

Manage database backup schedules and execution history.

```APIDOC
## `database_backups` Tool

Full lifecycle management for database backup schedules and execution history.

### Create Daily Backup with S3 Storage

**Description**: Creates a daily database backup with specified retention policies and S3 storage configuration.

**Tool**: `database_backups`

**Action**: `create`

**Parameters**:
- **database_uuid** (string) - Required - The UUID of the database to back up.
- **frequency** (string) - Required - The cron schedule for backups (e.g., "0 2 * * *").
- **enabled** (boolean) - Required - Whether the backup schedule is enabled.
- **save_s3** (boolean) - Required - Whether to save backups to S3.
- **s3_storage_uuid** (string) - Required if `save_s3` is true - The UUID of the S3 storage configuration.
- **database_backup_retention_days_locally** (integer) - Optional - Number of days to retain backups locally.
- **database_backup_retention_days_s3** (integer) - Optional - Number of days to retain backups in S3.

### List Backup Schedules

**Description**: Lists all backup schedules for a given database.

**Tool**: `database_backups`

**Action**: `list_schedules`

**Parameters**:
- **database_uuid** (string) - Required - The UUID of the database.

**Response Example**:
```json
[
  { "uuid": "bk1", "frequency": "0 2 * * *", "enabled": true }
]
```

### List Backup Executions

**Description**: Views the execution history for a specific backup schedule.

**Tool**: `database_backups`

**Action**: `list_executions`

**Parameters**:
- **database_uuid** (string) - Required - The UUID of the database.
- **backup_uuid** (string) - Required - The UUID of the backup schedule.

### Update Backup Schedule

**Description**: Updates an existing backup schedule, for example, to disable it.

**Tool**: `database_backups`

**Action**: `update`

**Parameters**:
- **database_uuid** (string) - Required - The UUID of the database.
- **backup_uuid** (string) - Required - The UUID of the backup schedule to update.
- **enabled** (boolean) - Required - The new enabled state for the schedule.
```

--------------------------------

### Create Application from Private GitHub App

Source: https://context7.com/stumason/coolify-mcp/llms.txt

Deploys an application using a private GitHub App. Requires project and server UUIDs, GitHub App UUID, repository, branch, and optional health check configurations.

```typescript
// Deploy from private GitHub App
// tool: "application"
{
  "action": "create_github",
  "project_uuid": "proj1",
  "server_uuid": "srv1",
  "github_app_uuid": "gh-app-1",
  "git_repository": "org/private-repo",
  "git_branch": "main",
  "health_check_enabled": true,
  "health_check_path": "/health",
  "health_check_interval": 30,
  "health_check_retries": 3
}
```

--------------------------------

### List Services

Source: https://github.com/stumason/coolify-mcp/blob/main/README.md

Retrieve a summary list of all services.

```text
list_services
```

--------------------------------

### Run Lint Command

Source: https://github.com/stumason/coolify-mcp/blob/main/CONTRIBUTING.md

Execute this command to check code for linting errors.

```bash
npm run lint
```

--------------------------------

### List GitHub Apps

Source: https://context7.com/stumason/coolify-mcp/llms.txt

Retrieves a summary list of all integrated GitHub Apps.

```typescript
// List GitHub Apps (summary)
// tool: "github_apps"
{ "action": "list" }
```

--------------------------------

### Find Infrastructure Issues

Source: https://github.com/stumason/coolify-mcp/blob/main/README.md

Scan your entire infrastructure for any unhealthy applications, databases, services, or unreachable servers.

```text
Find any issues in my infrastructure
```

--------------------------------

### CoolifyClient API Calls: Version and Server List

Source: https://context7.com/stumason/coolify-mcp/llms.txt

Retrieve the Coolify API version and list servers with compact summaries using the CoolifyClient. Caches version after the first call.

```typescript
// Version (plain-text endpoint, result is cached after first call)
const { version } = await client.getVersion();
// => { version: "v4.0.0-beta.460" }

// List servers as compact summaries
const servers = await client.listServers({ summary: true });
// => [{ uuid: "abc123", name: "vps-01", ip: "1.2.3.4", status: "running", is_reachable: true }]
```

--------------------------------

### Create PostgreSQL Database

Source: https://context7.com/stumason/coolify-mcp/llms.txt

Creates a PostgreSQL database. Optional fields include user, password, and database name; defaults are generated if omitted. Requires server and project UUIDs, environment name, and database name.

```typescript
// Create a PostgreSQL database
// tool: "database"
{
  "action": "create",
  "type": "postgresql",
  "server_uuid": "srv1",
  "project_uuid": "proj1",
  "environment_name": "production",
  "name": "prod-db",
  "postgres_user": "app",
  "postgres_password": "s3cr3t",
  "postgres_db": "myapp",
  "instant_deploy": true,
  "is_public": false
}
// => { "data": { "uuid": "db-new-uuid" } }
```

--------------------------------

### Trigger Deployment by UUID or Tag

Source: https://context7.com/stumason/coolify-mcp/llms.txt

Initiates a deployment for an application, either by its unique UUID or a deployment tag. Supports forcing a redeployment.

```typescript
// Deploy by application UUID
// tool: "deploy"
{ "tag_or_uuid": "xs0sgs4gog044s4k4c88kgsc", "force": true }
```

```typescript
// Deploy by tag
// tool: "deploy"
{ "tag_or_uuid": "production", "force": false }
```

--------------------------------

### Environment Variables Tool

Source: https://context7.com/stumason/coolify-mcp/llms.txt

Manages environment variables for applications and services, supporting listing, creation, updating, and deletion.

```APIDOC
## `env_vars` Tool

Manages environment variables for applications and services (list, create, update, delete).

### List Environment Variables
```json
{ "tool": "env_vars", "args": { "resource": "application", "action": "list", "uuid": "app1" } }
```

#### Response Example
```json
[ { "uuid": "env1", "key": "DATABASE_URL", "value": "postgres://...", "is_build_time": false } ]
```

### Create Environment Variable
```json
{ "tool": "env_vars", "args": { "resource": "application", "action": "create", "uuid": "app1", "key": "REDIS_URL", "value": "redis://localhost:6379" } }
```

### Update Environment Variable
```json
{ "tool": "env_vars", "args": { "resource": "application", "action": "update", "uuid": "app1", "key": "DATABASE_URL", "value": "postgres://new-host/db" } }
```

### Delete Environment Variable
```json
{ "tool": "env_vars", "args": { "resource": "application", "action": "delete", "uuid": "app1", "env_uuid": "env1" } }
```
```

--------------------------------

### Cloud Tokens Tool

Source: https://context7.com/stumason/coolify-mcp/llms.txt

Manages Hetzner and DigitalOcean API tokens stored in Coolify for server provisioning. You can create, validate, list, and delete these tokens.

```APIDOC
## Cloud Tokens Tool

### Description
Manages Hetzner and DigitalOcean API tokens stored in Coolify for server provisioning.

### Actions

#### Create Cloud Token
**Description:** Creates a new cloud token for a specified provider.
**Tool:** `cloud_tokens`
**Action:** `create`
**Parameters:**
- **provider** (string) - Required - The cloud provider (e.g., 'hetzner').
- **token** (string) - Required - The API token for the provider.
- **name** (string) - Required - A descriptive name for the token.
**Request:**
```json
{ "action": "create", "provider": "hetzner", "token": "hcloud-token-xxx", "name": "hetzner-prod" }
```
**Response Example:**
```json
{ "data": { "uuid": "ct-uuid" } }
```

#### Validate Cloud Token
**Description:** Validates a stored cloud token against its respective provider API.
**Tool:** `cloud_tokens`
**Action:** `validate`
**Parameters:**
- **uuid** (string) - Required - The unique identifier of the token to validate.
**Request:**
```json
{ "action": "validate", "uuid": "ct-uuid" }
```
**Response Example:**
```json
{ "data": { "valid": true, "message": "Token is valid." } }
```

#### List Cloud Tokens
**Description:** Retrieves a list of all stored cloud tokens.
**Tool:** `cloud_tokens`
**Action:** `list`
**Request:**
```json
{ "action": "list" }
```

#### Delete Cloud Token
**Description:** Deletes a cloud token identified by its UUID.
**Tool:** `cloud_tokens`
**Action:** `delete`
**Parameters:**
- **uuid** (string) - Required - The unique identifier of the token to delete.
**Request:**
```json
{ "action": "delete", "uuid": "ct-uuid" }
```
```

--------------------------------

### projects

Source: https://context7.com/stumason/coolify-mcp/llms.txt

Consolidated CRUD operations for Coolify projects.

```APIDOC
## `projects` Tool

Consolidated CRUD for Coolify projects using an `action` parameter.

### Arguments

- `action` (string): The operation to perform. Possible values: `create`, `list`, `update`, `delete`.
- `name` (string, optional): The name of the project (required for `create` and `update`).
- `description` (string, optional): The description of the project (required for `create`).
- `uuid` (string, optional): The unique identifier of the project (required for `update` and `delete`).

### Examples

**Create a project:**
```typescript
// tool: "projects"  args: { action: "create", name: "my-app", description: "Production workload" }
// => { "data": { "uuid": "proj-new-uuid" } }
```

**List projects:**
```typescript
// tool: "projects"  args: { action: "list" }
// => { "data": [{ "uuid": "proj1", "name": "my-app", "description": "Production workload" }] }
```

**Update a project:**
```typescript
// tool: "projects"  args: { action: "update", uuid: "proj1", name: "my-app-v2" }
```

**Delete a project:**
```typescript
// tool: "projects"  args: { action: "delete", uuid: "proj1" }
```
```