dokploy-mcp-server

A comprehensive Model Context Protocol (MCP) server for Dokploy - 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 covers only ~5 of 42 API categories. This server provides 13 tools (one per category with action enums) covering the full DevOps lifecycle with minimal token usage.

Feature Comparison

| Category | Official MCP | This Server | | -------------- | ------------------- | ----------------------------- | | Projects | 6 tools | 1 tool (6 actions) | | Applications | 26 tools | 1 tool (18 actions) | | Compose | - | 1 tool (15 actions) | | Deployments | - | 1 tool (2 actions) | | Docker | - | 1 tool (4 actions) | | Domains | 9 tools | 1 tool (8 actions) | | Servers | - | 1 tool (8 actions) | | Settings | - | 1 tool (5 actions) | | Databases | 26 tools (pg+mysql) | 1 tool (13 actions, all 5 DB) | | Backups | - | 1 tool (6 actions) | | Environments | - | 1 tool (6 actions) | | Infrastructure | - | 1 tool (8 actions) | | SSH Keys | - | 1 tool (6 actions) | | Total | 67 tools | 13 tools |

Key advantages:

• Minimal token usage - 13 tools instead of 67+, dramatically reducing context consumption
• Unified database tool - One tool handles all 5 database types (postgres, mysql, mariadb, mongo, redis) via dbType + action params
• Full API coverage - Docker Compose, containers, servers, deployments, backups, certificates, ports, and basic auth
• Action-based design - Each tool has an action enum parameter; other params are optional based on action

Installation

Claude Desktop / Claude Code

Add to your MCP configuration:

{
  "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:

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

Docker

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 (13)

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.

dokploy_application (18 actions)

Actions: create | get | update | move | deploy | start | stop | delete | markRunning | refreshToken | cleanQueues | killBuild | cancelDeployment | reload | saveEnvironment | saveBuildType | traefikConfig | readMonitoring

Full application lifecycle. Most actions require applicationId. create requires name + environmentId. deploy supports redeploy flag. readMonitoring requires appName.

dokploy_compose (15 actions)

Actions: create | get | update | delete | deploy | start | stop | move | loadServices | loadMounts | getDefaultCommand | cancelDeployment | cleanQueues | killBuild | refreshToken

Docker Compose management. Most actions require composeId. create requires name + environmentId. loadMounts requires serviceName. cancelDeployment/cleanQueues/killBuild/refreshToken require composeId.

dokploy_database (13 actions)

Actions: create | get | update | move | start | stop | deploy | rebuild | remove | reload | changeStatus | saveEnvironment | saveExternalPort

Unified database management. All actions require dbType (postgres/mysql/mariadb/mongo/redis). Most also require databaseId.

dokploy_domain (8 actions)

Actions: create | list | get | update | delete | generate | canGenerateTraefikMe | validate

Domain/DNS management. create requires host + applicationId|composeId. validate requires domain.

dokploy_environment (6 actions)

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

Project environment management. create requires projectId + name. list requires projectId.

dokploy_server (8 actions)

Actions: list | get | create | update | remove | count | publicIp | getMetrics

Server management. create requires name + ipAddress + port + username + sshKeyId + serverType. getMetrics requires url + token.

dokploy_backup (6 actions)

Actions: create | get | update | remove | listFiles | manualBackup

Backup scheduling and triggers. create requires schedule + prefix + destinationId + database + databaseType. manualBackup requires backupId + backupType.

dokploy_deployment (2 actions)

Actions: list | killProcess

Deployment tracking. list requires applicationId|composeId|serverId|type+id. killProcess requires deploymentId.

dokploy_docker (4 actions)

Actions: getContainers | restartContainer | getConfig | findContainers

Container management. findContainers requires appName + method (match|label|stack|service).

dokploy_infrastructure (8 actions)

Actions: createPort | deletePort | createAuth | deleteAuth | listCerts | getCert | createCert | removeCert

Ports, basic auth, and SSL certificates.

dokploy_ssh_key (6 actions)

Actions: create | list | get | update | remove | generate

SSH key management for git-based deployments. create requires name + privateKey + publicKey + organizationId. get requires sshKeyId. update requires sshKeyId, optional name, description, lastUsedAt. remove requires sshKeyId. generate uses type (rsa|ed25519).

dokploy_settings (5 actions)

Actions: health | version | ip | clean | reload

System settings. clean uses cleanType (all|images). reload uses reloadTarget (server|traefik).

Usage Examples

Deploy an application

"Deploy my web app" → dokploy_application { action: "deploy", applicationId: "app-123" }

Start a PostgreSQL database

"Start the postgres database" → dokploy_database { action: "start", dbType: "postgres", databaseId: "db-456" }

Check system health

"Is Dokploy healthy?" → dokploy_settings { action: "health" }

List all containers

"What containers are running?" → dokploy_docker { action: "getContainers" }

Development

pnpm install
pnpm dev          # Development mode with watch
pnpm validate     # Format + lint + test + build
pnpm inspect      # Open MCP Inspector

License

MIT

Sponsored by SapientsAI — Building agentic AI for businesses