Dokploy MCP Server: 508 Dokploy API Tools Inside Your AI Client

What Dokploy MCP Server actually solves

Dokploy is a self-hostable deployment platform, and it already has an HTTP API. The gap this package fills is not access, it is shape. An MCP client cannot call a REST endpoint; it calls tools that have names, JSON schemas and descriptions. Dokploy MCP Server is the adapter that makes every Dokploy API endpoint look like one of those tools.

The README puts the scope at 508 tools across 49 categories, covering project and application management, databases, notifications, SSO, Docker and backups. That is the entire API surface, not a hand-picked subset. The audience is narrow and specific: people who run Dokploy and who already work inside an MCP client such as Cursor, VS Code, Claude Desktop or Claude Code. If you do not have a running Dokploy server, there is nothing here for you to connect to.

How 508 tools get generated from openapi.json

The repository layout explains the mechanism better than the README does. There is an openapi.json at the top level, a scripts/ directory, and two package.json scripts that matter: fetch-openapi and generate. Running generate:all chains them.

So the pipeline is: pull the Dokploy OpenAPI description, then generate TypeScript tool definitions from it. That is why the tool count tracks the API rather than a maintainer's judgement about which operations are worth exposing. The runtime then serves those tools over the Model Context Protocol through @modelcontextprotocol/sdk, with hono and @hono/node-server handling the HTTP transport and zod plus zod-to-json-schema producing the input schemas.

The design consequence is worth stating plainly. A generated surface is complete and consistent, and it is also indifferent. Every endpoint becomes a tool, including destructive ones. There is no curation layer that decides some operations are too dangerous to hand to a language model.

Installing Dokploy MCP Server in Claude Code and Cursor

You need Node.js 18 or newer, an MCP client, and a running Dokploy server with an API key. The package is published as @dokploy/mcp on npm, so most clients launch it through npx rather than a global install.

For Claude Code, the README gives a CLI command that registers the server:

claude mcp add dokploy-mcp -- npx -y @dokploy/mcp

Then supply the two environment variables, either in .claude/settings.json or inline before launching the client:

DOKPLOY_URL=https://your-dokploy-server.com DOKPLOY_API_KEY=your-token claude

For Cursor, the same server is declared in ~/.cursor/mcp.json (or .cursor/mcp.json inside a project). The env block is where the Dokploy URL and key go:

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

The README also documents the same block for Windsurf, Claude Desktop and BoltAI, a VS Code variant that adds "type": "stdio" and uses the key "servers" instead of "mcpServers", a Zed variant under "context_servers", and an Opencode variant under "mcp" with "type": "local" and an "environment" key. Bun and Deno alternatives swap the command for bunx or deno run with --allow-env --allow-net. After a client restart, the Dokploy tools should appear in the tool list.

Running it with Docker in HTTP or stdio mode

The container supports both transports, which is what makes it usable outside a desktop client. The Dockerfile builds with pnpm, copies the compiled build directory into a Node alpine image, installs production dependencies only, and exposes port 3000 internally. A health check probes http://localhost:3000/health when MCP_TRANSPORT is http or sse, and skips itself otherwise.

Build the image from a clone:

git clone https://github.com/Dokploy/mcp.git
cd mcp
docker build -t dokploy-mcp .

For HTTP mode, map the internal port and set the transport variable:

docker run -it --rm \
  -p 8080:3000 \
  -e MCP_TRANSPORT=http \
  -e DOKPLOY_URL=https://your-dokploy-server.com \
  -e DOKPLOY_API_KEY=your_token_here \
  dokploy-mcp

The provided docker-compose.yml defines two services, dokploy-mcp-http and dokploy-mcp-stdio, both reading DOKPLOY_URL and DOKPLOY_API_KEY from the environment with placeholder defaults. The HTTP service maps ${EXTERNAL_PORT:-3000} to 3000 and restarts unless-stopped; the stdio service sets restart to "no" and keeps stdin open. Note that the compose defaults are literal placeholders, so an unset DOKPLOY_API_KEY will start a container that cannot authenticate.

Redaction, custom headers and category filtering

The .env.example is where the operational thinking shows. Three optional variables change the server's behaviour.

DOKPLOY_REDACT_ENV is on by default and strips secret-bearing fields from API responses before they reach the MCP client. The default field list is long and includes env, buildArgs, composeFile, dockerCompose, environment, buildSecrets, previewBuildSecrets, the various database password fields, registryPassword, token, accessToken, apiToken, refreshToken, secret, clientSecret, apiKey, secretAccessKey, accessKey, licenseKey, privateKey, sshKey, dockerAuth and more. Setting it to false returns unredacted responses. DOKPLOY_REDACT_FIELDS overrides that list with your own comma-separated names.

DOKPLOY_ENABLED_TAGS filters which tool categories load, for example project,application,postgres. This is the closest thing to a safety dial: with 508 tools in the default configuration, every client session carries the full surface, and narrowing the tags reduces both the context cost and the number of destructive operations a model can reach.

DOKPLOY_CUSTOM_HEADERS takes a JSON object of extra upstream headers, with x-api-key, content-type and accept reserved and rejected. The documented use case is Cloudflare Access service tokens.

My read: redaction being on by default is the right call, but it also means an agent asking for an application's environment variables gets a masked answer and may report back as if the values were empty. That is a real source of confusing agent behaviour, and it is not something the README warns about.

Where this is the wrong tool

The failure mode is proportional to the tool count. Exposing all 508 endpoints means an agent with a valid API key can delete an application, drop a database or trigger a backup just as easily as it can list projects. The README does not document a confirmation step, a dry-run mode or a rollback path for destructive operations. If you need a guardrail between a language model and production infrastructure, this package does not provide one; DOKPLOY_ENABLED_TAGS is a blunt filter, not an approval gate.

Context is the second constraint. Fifty-plus categories of tool definitions have to be described to the model. The README does not state how much of a client's context window the tool list consumes, and that number will differ by client, but a full-surface server is heavier than a focused one.

The third case is simpler. If you do not run Dokploy, or if you only ever need one or two API calls, a short script against the Dokploy API is less machinery than an MCP server plus a client configuration.

Compared with calling the Dokploy API directly

The alternative is not another MCP server; it is the Dokploy API itself, called from a script or a CI job. The difference is who chooses the operation. A script hard-codes the endpoint and the payload, so the set of things it can do is fixed at review time and visible in a diff. Dokploy MCP Server inverts that: the operation is chosen at runtime by a model, from a generated list of 508, and the only review point is the API key's scope.

That trade is not automatically bad. For read-heavy work such as surveying projects, checking deployment state or listing database services, letting a model pick the endpoint is faster than writing a wrapper. For write operations on production, the script is the safer artefact because it is auditable before it runs. A reasonable split is to keep the MCP server for discovery and diagnosis, and keep the actual deploys in whatever pipeline you already trust.

Licence, maintenance and upgrade cost

package.json declares Apache-2.0, while the repository metadata reports NOASSERTION. The discrepancy is worth resolving with whoever reviews licences on your side before you redistribute anything; I am not in a position to say which governs. Apache-2.0 as declared in package.json is a permissive licence with an explicit patent grant and a requirement to preserve notices, but that is a description, not legal advice.

Maintenance looks current: the last push was on 2026-09-09, and releases v0.30.4, v0.30.5 and v0.30.6 landed between 2026-09-01 and 2026-09-08. The version numbering suggests fast iteration, which fits a generated surface that has to track a moving API.

The upgrade cost is tied to that generation step. Because tools are derived from openapi.json, a Dokploy API change can alter or remove tool definitions, and an agent prompt that names a tool may break when the name changes. Pinning @dokploy/mcp to a specific version in your client config, rather than relying on the floating latest tag some of the README examples use, is the practical way to keep an agent workflow stable. The README does not document a changelog or a deprecation policy for tool names.

Editorial conclusion

Adopt Dokploy MCP Server if you already run a Dokploy instance and want an MCP client to read and change projects, applications and databases through natural language instead of clicking through the panel. Skip it if you want a curated set of safe operations, if you have no Dokploy server, or if you cannot hand a full-access API key to a client. Before wiring it into a team workflow, verify three things: that DOKPLOY_REDACT_ENV is left at its default, that DOKPLOY_ENABLED_TAGS is narrowed to the categories you actually need, and that your Dokploy API key is scoped as tightly as your Dokploy version allows.

Frequently asked questions

Official sources

1. Dokploy/mcp on GitHub
2. Issues
3. README
4. Releases