dokploy-mcp-connector

An MCP server that connects Claude Desktop (or any MCP client) to your self-hosted Dokploy instance.

You give it two things — your Dokploy URL and an API key — and Claude can list projects, deploy applications, manage databases and domains, read logs, and reach every procedure the Dokploy API exposes.

Setup (one command)

Run the interactive setup — it asks for your Dokploy URL and API key, tests the connection, and writes the Claude Desktop config for you automatically:

npx dokploy-mcp-connector init

Then fully quit and reopen Claude Desktop. That's it — works the same on macOS, Windows, and Linux (anywhere Node 18+ is installed).

Not sure what to run? Ask the tool itself:

npx dokploy-mcp-connector help

It prints the setup steps and the exact config path for your operating system.

Manual setup (alternative)

If you'd rather edit the config yourself: Claude Desktop → Settings → Developer → Edit Config, then add:

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

Restart Claude Desktop.

Getting your API key

In Dokploy: Settings → Profile → API/CLI → Generate Token. Admins may need to grant your user API access first.

DOKPLOY_URL

Use the base of your instance — with or without a scheme, port, or trailing /api; the server normalizes it:

• https://dokploy.example.com
• http://1.2.3.4:3000

Tools

| Tool | What it does | |---|---| | dokploy_list_projects | Summary of all projects → services (id, name, status). detail: true for the full config. | | dokploy_get_project | Fetch one project by id, in full. | | dokploy_list_operations | Search every API operation by keyword (deploy, postgres, domain, backup, …), ranked by relevance. | | dokploy_describe_operation | Every parameter (name, type, required) for one operation — for building create/update calls. | | dokploy_call | Invoke any operation by path + params. Method and param placement are inferred from the catalog. |

How "all functions" works

Dokploy exposes ~546 RPC procedures. Rather than freeze a giant hardcoded list — or register 546 tools, which would permanently occupy Claude's context — the server loads the OpenAPI document from your own instance at runtime, so discovery always matches your version. Ask Claude things like "deploy my api app" — it searches operations, then calls the right one via dokploy_call.

Performance

The connector is tuned to keep Claude fast, since every byte it returns occupies the context window for the rest of the conversation. Measured against a live instance serving a 680 KB / 546-operation spec:

| | Before | After | |---|---|---| | Cold start (first search) | ~4.6 s (3 probes) | ~1.4 s (1 probe) | | Start with warm cache | ~4.6 s, every restart | ~1 ms | | list_operations result | ~31.5 KB (~7,900 tokens) | ~1.2 KB (~310 tokens) | | list_projects (2 projects, 10 services) | ~44 KB (~11,000 tokens) | ~0.8 KB (~210 tokens) |

How:

• Dense signatures. Search returns one line per operation (POST application.deploy body: applicationId*) instead of a JSON object per operation with every optional parameter expanded.
• Compact JSON. Results are no longer pretty-printed — indentation alone was ~47% of the bytes.
• Disk cache. The parsed catalog is cached in the OS temp dir for 24 h, keyed by instance origin, so Claude Desktop restarts don't re-download the spec. An expired cache is still used if the instance is unreachable.
• Summaries by default. project.all returns every app's env vars, ports, mounts, and compose files. dokploy_list_projects collapses that to ids, names, and statuses; pass detail: true when you actually need the rest.
• Truncation. Any single result is capped at 60,000 characters with an explicit notice, so one log call can't consume the window.
• Timeouts. Requests abort after 60 s rather than hanging Claude forever.

Tuning

| Env var | Default | Purpose | |---|---|---| | DOKPLOY_REVEAL_SECRETS | false | Show plaintext secrets (see below). | | DOKPLOY_TIMEOUT_MS | 60000 | Per-request timeout. | | DOKPLOY_CACHE_TTL_HOURS | 24 | Catalog cache lifetime. Set 0 to always refetch. |

Security: secret redaction

The Dokploy API returns database passwords and env vars in plaintext. By default this server masks values whose keys look sensitive (password, secret, token, …) before returning results to Claude. The policy lives in src/redact.ts.

To let Claude see plaintext secrets (e.g. to help you rotate a leaked credential), set DOKPLOY_REVEAL_SECRETS=true in the env block.

Troubleshooting

npm error code EACCES ... mkdir .../.npm/_cacache in Claude Desktop's logs. This is a machine-level npm cache permission problem (not specific to this package) — usually caused by a past sudo npm .... It stops npx from running anything. Fix it once:

sudo chown -R "$(id -u):$(id -g)" "$HOME/.npm"

(On Windows this specific error doesn't occur.) Alternatively, avoid the shared cache by adding "npm_config_cache": "<a-folder-you-own>" to the env block in your Claude Desktop config. Then fully quit and reopen Claude Desktop.

Nothing happens / "Missing DOKPLOY_URL" in the logs. The server started but has no credentials — run npx dokploy-mcp-connector init and restart Claude Desktop.

Local development

npm install
npm run build
DOKPLOY_URL=... DOKPLOY_API_KEY=... npm start

License

MIT