dokploy-mcp-server

# dokploy-mcp-server

[![npm version](https://img.shields.io/npm/v/dokploy-mcp-server)](https://www.npmjs.com/package/dokploy-mcp-server)

A comprehensive [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server for [Dokploy](https://dokploy.com/) - the open-source, self-hosted PaaS. Deploy apps, manage containers, databases, domains, and servers through AI assistants like Claude.

## Why This Server?

The [official Dokploy MCP](https://github.com/Dokploy/mcp) generates one tool per API endpoint — at the 0.29.14 measurement below, 546 of them, exactly matching the 546 paths in Dokploy's OpenAPI spec at that version. (Dokploy v0.30.2 ships 597 paths; the figures in this section are left at their measured values rather than re-estimated.) Coverage is complete, and every one of those schemas loads into the model's context before you ask your first question.

This server hand-curates the same API into **27 tools** (one per category, each taking an `action` enum), covering the deploy-and-operate surface most self-hosters use daily.

### Context cost

|                                    | Official `@dokploy/mcp` | This server      |
| ---------------------------------- | ----------------------- | ---------------- |
| Tools exposed                      | 546                     | 22 (21 + `info`) |
| `tools/list` schema payload        | 294,957 bytes           | 34,528 bytes     |
| Approximate tokens loaded up front | **~74k**                | **~8.6k**        |
| Median tool schema                 | 388 bytes               | 1,131 bytes      |

Measured 2026-08-08 against `@dokploy/mcp@0.29.14` and `dokploy-mcp-server@1.8.2`, by starting each server, calling `tools/list`, and counting the serialized schema bytes (divided by 4 for a rough token estimate).

Since that measurement this server grew to 27 tools tracking Dokploy v0.30.2. Measured the same way — live `tools/list` over stdio — it now exposes 28 tools (27 + `info`) for **48,452 bytes (~12.1k tokens)**. The official server has not been re-measured against 0.30.2, so the table above is left at the paired 0.29.14 figures rather than mixing a new number for one side with an old one for the other.

On a 200k-token context window, the official server spends more than a third of it before you ask anything. The larger median schema here is deliberate: descriptions carry the workflow knowledge that prevents failed calls, such as which service id pairs with which `databaseType`.

### Feature Comparison

Tool counts for the official server are per category, taken from its live `tools/list`.

| Category            | Official MCP           | This Server                   |
| ------------------- | ---------------------- | ----------------------------- |
| Projects            | 9 tools                | 1 tool (6 actions)            |
| Applications        | 31 tools               | 1 tool (23 actions)           |
| Compose             | 31 tools               | 1 tool (21 actions)           |
| Deployments         | 9 tools                | 1 tool (5 actions)            |
| Docker              | 12 tools               | 1 tool (17 actions)           |
| Docker Volumes      | n/a (new in 0.30.2)    | 1 tool (8 actions)            |
| Docker Images       | n/a (new in 0.30.2)    | 1 tool (3 actions)            |
| Networks            | n/a (new in 0.30.2)    | 1 tool (8 actions)            |
| Overview            | n/a (new in 0.30.2)    | 1 tool (3 actions)            |
| DNS Providers       | n/a (new in 0.30.2)    | 1 tool (11 actions)           |
| Vault Providers     | n/a (new in 0.30.2)    | 1 tool (7 actions)            |
| Domains             | 9 tools                | 1 tool (9 actions)            |
| Redirects           | 4 tools                | 1 tool (4 actions)            |
| Servers             | 18 tools               | 1 tool (8 actions)            |
| Settings            | 54 tools               | 1 tool (5 actions)            |
| Databases           | 94 tools (6 engines)   | 1 tool (17 actions, all 6 DB) |
| Backups             | 12 tools               | 1 tool (6 actions)            |
| Volume Backups      | 6 tools                | 1 tool (6 actions)            |
| Preview Deployments | 4 tools                | 1 tool (4 actions)            |
| Schedules           | 6 tools                | 1 tool (6 actions)            |
| Audit Log           | 1 tool                 | 1 tool (1 action)             |
| Environments        | 7 tools                | 1 tool (6 actions)            |
| Infrastructure      | 13 tools (ports+certs) | 1 tool (8 actions)            |
| Mounts              | 6 tools                | 1 tool (6 actions)            |
| SSH Keys            | 7 tools                | 1 tool (6 actions)            |
| Registries          | 7 tools                | 1 tool (7 actions)            |
| Destinations        | 6 tools                | 1 tool (6 actions)            |
| **Total**           | **346 tools**          | **27 tools**                  |

Key advantages:

- **Minimal token usage** - 346 endpoints' worth of surface in 27 tools, for roughly an eighth of the context
- **Unified database tool** - One tool handles all 6 database types (postgres, mysql, mariadb, mongo, redis, libsql) via `dbType` + `action` params
- **Curated descriptions** - Each tool documents which parameters pair with which action, so calls succeed on the first try
- **Action-based design** - Each tool has an `action` enum parameter; other params are optional based on action

### When to use the official server instead

The official server covers 49 categories to this server's 27. Of its 546 tools, 346 fall inside the categories above; the remaining 200 have no equivalent here:

- **Notifications** (41 tools) - email, Slack, Discord, Telegram, Gotify webhooks
- **Users, organizations, roles, SSO** (64 tools) - user management, organizations, custom roles, SSO, SCIM, forwardAuth
- **Git providers** (32 tools) - GitHub, GitLab, Gitea, Bitbucket app configuration
- **AI providers** (14 tools) - Dokploy's own LLM integration for log analysis and compose generation
- **Cluster and Swarm** (8 tools), **patch** (12), **tags** (8), **rollback** (2), **admin** (1)
- **Dokploy Cloud commercial features** (18 tools) - Stripe billing, license keys, whitelabeling

If your workflow needs any of those, use the official server, or run both.

## Installation

### Claude Desktop / Claude Code

Add to your MCP configuration:

```json
{
  "mcpServers": {
    "dokploy": {
      "command": "npx",
      "args": ["-y", "dokploy-mcp-server"],
      "env": {
        "DOKPLOY_URL": "https://dokploy.example.com",
        "DOKPLOY_API_KEY": "your-api-key"
      }
    }
  }
}
```

### Cursor

Add to `.cursor/mcp.json`:

```json
{
  "mcpServers": {
    "dokploy": {
      "command": "npx",
      "args": ["-y", "dokploy-mcp-server"],
      "env": {
        "DOKPLOY_URL": "https://dokploy.example.com",
        "DOKPLOY_API_KEY": "your-api-key"
      }
    }
  }
}
```

### Docker

```bash
docker run -e DOKPLOY_URL=https://dokploy.example.com \
           -e DOKPLOY_API_KEY=your-api-key \
           -e TRANSPORT_TYPE=httpStream \
           -p 3000:3000 \
           dokploy-mcp-server
```

## Environment Variables

| Variable          | Required | Default   | Description                              |
| ----------------- | -------- | --------- | ---------------------------------------- |
| `DOKPLOY_URL`     | Yes      | -         | Your Dokploy instance URL                |
| `DOKPLOY_API_KEY` | Yes      | -         | API key from Dokploy Settings > API Keys |
| `TRANSPORT_TYPE`  | No       | `stdio`   | Transport mode: `stdio` or `httpStream`  |
| `PORT`            | No       | `3000`    | HTTP port (httpStream mode only)         |
| `HOST`            | No       | `0.0.0.0` | HTTP host (httpStream mode only)         |

## Tools (27)

Each tool uses an `action` enum to select the operation. Parameters are optional and used based on the chosen action.

### `dokploy_project` (6 actions)

Actions: `list | get | create | update | remove | duplicate`

Manage projects. `list` and `get` return nested environments with their applications, composes, and databases (with names, IDs, and status), so you can discover service IDs without extra calls. `create` requires `name`. `update` requires `projectId` + fields. `remove` requires `projectId`. `duplicate` requires `sourceEnvironmentId` + `name`.

**Reading the status label.** Dokploy's status enum is `idle | running | done | error`, rendered as `[IDLE]`, `[RUNNING]`, `[DONE]`, `[ERROR]`. It describes the **deployment**, not live container state — `[DONE]` means the last deploy finished, and `[IDLE]` means nothing has run, neither of which implies a container is up right now. Check `dokploy_docker` `getContainers` for what is actually running.

### `dokploy_application` (23 actions)

Actions: `create | get | update | move | deploy | start | stop | delete | markRunning | refreshToken | cleanQueues | killBuild | cancelDeployment | reload | saveEnvironment | setEnvVars | getEnvKeys | getEnvValuesUnsafe | saveBuildType | traefikConfig | readMonitoring | readLogs | search`

Full application lifecycle. Most actions require `applicationId`. `create` requires `name` + `environmentId`. `deploy` supports `redeploy` flag. `readMonitoring` requires `appName`. `search` finds applications by `q`/`name`/`appName`/`repository`/`owner`/`dockerImage`/`projectId`/`environmentId`, with `limit` (1–100, default 20) and `offset`; the reply flags a truncated page.

**Env handling.** `get` returns a masked env summary (count only) — never the values. Three actions cover the rest:

- `setEnvVars` — granular merge inside the server. Pass `set` (KEY=VALUE per line, upsert) and/or `unset` (array of KEY names). The read-modify-write happens server-side; the tool result is a masked confirmation listing only the changed key names. No untouched-key values ever enter the transcript