Dokploy MCP Server

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?

Tracks Dokploy v0.30.8. Tools are built against the v0.30.8 OpenAPI spec (604 paths). The comparison below was measured on 2026-10-03.

The official Dokploy MCP generates one tool per API endpoint. Its latest release, @dokploy/mcp@0.30.7, exposes 604 tools, one for each of the 604 paths in Dokploy's v0.30.8 OpenAPI spec. 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

Measured 2026-10-03 against @dokploy/mcp@0.30.7 (the latest published) and this server's build tracking Dokploy v0.30.8. Each server was started over stdio, sent tools/list, and its serialized tool array counted in bytes (divided by 4 for a rough token estimate).

On a 200k-token context window, the official server spends about 40% of it before you ask anything; this server spends about 6.5%. 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 at @dokploy/mcp@0.30.7.

Key advantages:

• Minimal token usage - 399 endpoints' worth of surface in 27 tools, for about a sixth 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

Of the official server's 604 tools, 399 fall inside the categories above; the remaining 205 have no equivalent here:

• Notifications (41 tools) - email, Slack, Discord, Telegram, Gotify webhooks
• Users, organizations, roles, SSO (67 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 (20 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:

{

"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

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 (24 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 | deployNginxQuickstart

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. deployNginxQuickstart takes environmentId (+ optional serverId) and creates and deploys a "Hello World" nginx demo app on a generated traefik.me domain — Dokploy's onboarding smoke test.

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.
• getEnvKeys — returns KEY names only, sorted. Safe to read.
• getEnvValuesUnsafe — unsafe escape hatch that returns the full KEY=VALUE blob. Use only when you genuinely need the values; the output is in the tool transcript and any retained agent logs.
• saveEnvironment — full-replace, kept for explicit blob-set workflows.

sourceType:

• github → repository + owner + branch (+ githubId for private)
• git → customGitUrl + customGitBranch
• docker → dockerImage

buildType: dockerfile | heroku_buildpacks | paketo_buildpacks | nixpacks | static | railpack.

The underlying API also supports gitlab/bitbucket/gitea/drop sources, but those need provider-specific fields not yet exposed by this tool.

dokploy_compose (21 actions)

Actions: create | get | update | delete | deploy | start | stop | move | loadServices | loadMounts | getDefaultCommand | cancelDeployment | cleanQueues | killBuild | refreshToken | saveEnvironment | setEnvVars | getEnvKeys | getEnvValuesUnsafe | readLogs | search

Docker Compose management. Most actions require composeId. create requires name + environmentId. deploy takes optional redeploy and freshVolumes — `freshVolumes` runs `docker compose down --volumes` first, deleting the service's volume data (docker-compose type only). loadMounts requires serviceName. cancelDeployment/cleanQueues/killBuild/refreshToken require composeId. search takes the same query fields as dokploy_application.

Env handling. Same shape as dokploy_application: get returns a masked summary, setEnvVars merges, getEnvKeys lists key names, getEnvValuesUnsafe is the escape hatch, saveEnvironment full-replaces.

sourceType:

• github → repository + owner + branch (+ composePath)
• git → customGitUrl + customGitBranch (+ customGitSSHKeyId for private)

-