Remote OpenClaw
Menu

mcp-dokploy-fullapi-proxy

hl9020/mcp-dokploy-fullapi-proxy
0 starsCommunity

Install to Claude Code

This server doesn't publish a one-line install command. Follow the setup in the source repository.

Summary

A single-tool MCP proxy that exposes Dokploy's full tRPC API (473 endpoints) with multi-instance support and on-demand skill loading, saving 77-92% tokens compared to the official MCP.

README.md

mcp-dokploy-fullapi-proxy

Dokploy Version: v0.28.8 - 473 Endpoints _(last updated: 2026-03-27)_

Multi-instance Dokploy API proxy MCP. 1 tool, ~200 tokens instead of 67+ tools consuming ~35,000 tokens per conversation. Supports multiple Dokploy instances via config file.

How it works

A single MCP tool dokploy(method, params?, instance?) acts as a thin proxy to Dokploy's tRPC API. All intelligence lives in skill files that Claude reads on-demand via Progressive Disclosure - only the relevant API section is loaded into context, saving 77-92% tokens per request.

Setup

npx -y mcp-dokploy-fullapi-proxy

Configuration

Multi-Instance (recommended)

Create a config file at ~/.mcp-dokploy/config.json:

{
  "instances": {
    "prod": {
      "url": "https://dokploy.example.com/api",
      "token": "your-api-token"
    },
    "staging": {
      "url": "https://staging.dokploy.dev/api",
      "token": "another-api-token"
    }
  },
  "defaultInstance": "prod"
}

The config file is searched in this order:

  1. Path from DOKPLOY_CONFIG env var
  2. ./config.json (current working directory)
  3. ~/.mcp-dokploy/config.json (home directory)

Multi-Instance via env vars

For container/server deployments (Docker, Dokploy) where a config file is impractical, define multiple instances purely via env vars - two interchangeable styles:

A) JSON var (DOKPLOY_INSTANCES):

DOKPLOY_INSTANCES={"srv01":{"url":"https://a.example.com/api","token":"tok-a"},"hsh":{"url":"https://b.example.com/api","token":"tok-b"}}
DOKPLOY_DEFAULT_INSTANCE=srv01

B) Prefixed vars (DOKPLOY_<ID>_URL / DOKPLOY_<ID>_TOKEN):

DOKPLOY_SRV01_URL=https://a.example.com/api
DOKPLOY_SRV01_TOKEN=tok-a
DOKPLOY_HSH_URL=https://b.example.com/api
DOKPLOY_HSH_TOKEN=tok-b
DOKPLOY_DEFAULT_INSTANCE=srv01

The <ID> becomes a lowercase instance id (DOKPLOY_SRV01_URL -> srv01). Reserved names (URL, TOKEN, API, CONFIG, INSTANCES) are excluded so single-instance vars are not misparsed. DOKPLOY_DEFAULT_INSTANCE selects the default; otherwise default (if present) or the first id wins.

Require explicit instance: Set DOKPLOY_REQUIRE_INSTANCE=true to disable the silent default in multi-instance setups. Every dokploy() call must then pass instance explicitly, otherwise it errors. Prevents a fresh conversation from accidentally hitting the wrong instance. Has no effect with a single instance.

Single-Instance (env vars, backward-compatible)

For a single instance, env vars still work as before:

| Variable | Required | Default | Description | |----------|----------|---------|-------------| | DOKPLOY_URL | No | - | Dokploy API base URL (single instance, id default) | | DOKPLOY_TOKEN | No | - | API authentication token | | DOKPLOY_INSTANCES | No | - | JSON map of multiple instances | | DOKPLOY_<ID>_URL / _TOKEN | No | - | Prefixed per-instance vars | | DOKPLOY_DEFAULT_INSTANCE | No | - | Default instance id | | DOKPLOY_REQUIRE_INSTANCE | No | false | Force explicit instance on every call (multi-instance only) | | DOKPLOY_CONFIG | No | - | Path to config file |

When using env vars without a config file, a default instance is created automatically. Env vars are also merged as fallback into config-file setups.

Get your API token from Dokploy: Settings -> Profile -> API/Token Section.

Usage with instances

// Uses default instance
dokploy("project.all")

// Target a specific instance
dokploy("project.all", {}, { instance: "staging" })

Architecture: This MCP uses a two-part setup: 1. MCP Server - gives the AI tool access to the dokploy() function 2. Skill/Instructions - teaches the AI which endpoints exist and how to call them Without the skill, the AI has the tool but doesn't know the API. Tools that support native skill files get Progressive Disclosure (on-demand loading). Tools without skill support need the SKILL.md content injected as instructions.

---

Claude Desktop / Claude.ai

MCP: Native | Skills: Native (ZIP upload)

1. MCP Server

Add to claude_desktop_config.json:

  • Windows: %APPDATA%\Claude\claude_desktop_config.json
  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

With config file (multi-instance): ``json { "mcpServers": { "dokploy-fullapi-proxy": { "command": "npx", "args": ["-y", "mcp-dokploy-fullapi-proxy"] } } } ``

With env vars (single instance): ``json { "mcpServers": { "dokploy-fullapi-proxy": { "command": "npx", "args": ["-y", "mcp-dokploy-fullapi-proxy"], "env": { "DOKPLOY_URL": "https://your-dokploy-instance.com/api", "DOKPLOY_TOKEN": "your-api-token" } } } } ``

2. Skill Upload

  1. Download skill/dokploy-api.zip from this repo
  2. Go to Claude.ai / Claude Desktop -> Customize -> Skills
  3. Click + and upload dokploy-api.zip

---

Claude Code

MCP: Native | Skills: Native (.claude/skills/ directory)

1. MCP Server

claude mcp add dokploy-fullapi-proxy \
  -- npx -y mcp-dokploy-fullapi-proxy

Or with env vars for single instance:

claude mcp add dokploy-fullapi-proxy \
  -e DOKPLOY_URL=https://your-dokploy-instance.com/api \
  -e DOKPLOY_TOKEN=your-api-token \
  -- npx -y mcp-dokploy-fullapi-proxy

2. Skills

mkdir -p .claude/skills/dokploy-api
cp skill/*.md .claude/skills/dokploy-api/

---

Cursor

MCP: Native | Skills: Agent Skills (auto-discovered)

1. MCP Server

Add to ~/.cursor/mcp.json (global) or .cursor/mcp.json (project):

{
  "mcpServers": {
    "dokploy-fullapi-proxy": {
      "command": "npx",
      "args": ["-y", "mcp-dokploy-fullapi-proxy"]
    }
  }
}

2. Skills

mkdir -p .cursor/skills/dokploy-api
cp skill/*.md .cursor/skills/dokploy-api/

Or create a .cursor/rules/dokploy.mdc rule with SKILL.md contents.

---

Windsurf

MCP: Native | Skills: No native support (use Rules workaround)

1. MCP Server

Add to ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "dokploy-fullapi-proxy": {
      "command": "npx",
      "args": ["-y", "mcp-dokploy-fullapi-proxy"]
    }
  }
}

2. Skill Workaround

Create .windsurf/rules/dokploy.md with SKILL.md contents.

---

VS Code + GitHub Copilot

MCP: Native | Skills: No native support

1. MCP Server

Add to .vscode/mcp.json:

{
  "servers": {
    "dokploy-fullapi-proxy": {
      "command": "npx",
      "args": ["-y", "mcp-dokploy-fullapi-proxy"]
    }
  }
}

2. Skill Workaround

Paste SKILL.md contents into .github/copilot-instructions.md.

---

Cline

MCP: Native | Skills: No native support

Add MCP via Cline -> MCP Servers -> Edit. Paste SKILL.md into .clinerules.

---

Continue.dev

MCP: Native | Skills: No native support

Create .continue/mcpServers/dokploy.json with MCP config. Add SKILL.md to .continue/rules/dokploy.md.

---

OpenAI Codex CLI

MCP: Native | Skills: Native (.agents/skills/)

codex mcp add dokploy-fullapi-proxy \
  -- npx -y mcp-dokploy-fullapi-proxy

Copy skills: cp skill/*.md .agents/skills/dokploy-api/

---

Zed

MCP: Native | Skills: No native support

Add to Zed settings.json under context_servers. Use AGENTS.md for skill workaround.

---

Google Antigravity

MCP: Native | Skills: No native support

Add to ~/.gemini/settings.json. Use GEMINI.md for skill workaround.

---

Roo Code

MCP: Native | Skills: No native support

Configure via MCP settings panel. Add SKILL.md to .roo/rules/.

---

Compatibility Matrix

| Tool | MCP | Native Skills | Skill Workaround | Config Location | |------|:---:|:---:|:---:|---| | Claude Desktop / Claude.ai | Yes | ZIP Upload | - | claude_desktop_config.json | | Claude Code | Yes | .claude/skills/ | - | .mcp.json | | Cursor | Yes | Agent Skills | .cursor/rules/.mdc | .cursor/mcp.json | | Codex CLI | Yes | .agents/skills/ | - | .codex/config.toml | | Windsurf | Yes | No | .windsurf/rules/ | ~/.codeium/windsurf/mcp_config.json | | VS Code + Copilot | Yes | No | .github/copilot-instructions.md | .vscode/mcp.json | | Cline | Yes | No | .clinerules | MCP Settings JSON | | Continue.dev | Yes | No | .continue/rules/ | .continue/mcpServers/.json | | Zed | Yes | No | AGENTS.md | settings.json | | Google Antigravity | Yes | No | GEMINI.md / Rules | ~/.gemini/settings.json | | Roo Code | Yes | No | .roo/rules/ | MCP Settings JSON |

---

Skill files

The skill/ directory contains API docs split by resource (auto-generated from Dokploy's OpenAPI spec):

| File | Endpoints | Coverage | |------|-----------|----------| | SKILL.md | - | Entry point, routing table | | project.md | 14 | Projects & Environments | | app.md | 29 | Applications | | compose.md | 28 | Compose services | | domain.md | 9 | Domains & SSL | | database.md | 70 | PostgreSQL, MySQL, MariaDB, MongoDB, Redis | | deployment.md | 12 | Deployments, Preview, Rollback | | docker.md | 7 | Docker containers | | server.md | 23 | Server, Cluster, Swarm | | notification.md | 38 | Notifications | | settings.md | 73 | Settings, Admin, Stripe, SSO | | user.md | 27 | User & Organization | | git.md | 30 | Git Providers | | infra.md | 85 | Mounts, Redirects, Security, Ports, Backups, Certs, Registry, SSH, AI |

Token comparison

| | Official Dokploy MCP | mcp-dokploy-fullapi-proxy | |---|---|---| | Tools registered | 67 | 1 | | Permanent context tokens | ~35,000 | ~200 | | API coverage | ~16% (67 of 436) | 100% (473 endpoints) | | On-demand tokens per request | 0 | ~500-2,000 (1 skill file) | | Typical savings | - | 77-92% fewer tokens |

How the skill system works

User: "Deploy my app"
  -> Claude reads SKILL.md routing table (~500 tokens)
  -> Claude reads app.md (~1,600 tokens)
  -> Claude calls: dokploy("application.deploy", { applicationId: "..." })

pick - Response Filter

The pick parameter filters large API responses to only the fields you need:

// Without pick: entire project tree (~50KB, ~10,000 tokens)
dokploy("project.all")

// With pick: only MySQL instances (~200 tokens)
dokploy("project.all", {}, { pick: ["mysqlId", "name", "appName"] })

Recursively traverses the JSON response, retains only matching field names, removes empty objects/arrays.

Building the skill ZIP

# Windows
Compress-Archive -Path skill\* -DestinationPath dokploy-api.zip -Force

# macOS / Linux
cd skill && zip -r ../dokploy-api.zip . && cd ..

Verify

Start a new conversation and ask: `` Show me all Dokploy projects ``

With multi-instance: `` Show me all projects on staging ``

License

MIT

Related MCP servers

Browse all →

Apify MCP

apify/actors-mcp-server

Browser & ScrapingOpen

AWS MCP Servers

awslabs/mcp

9,330 starsOpen

Axiom MCP

axiomhq/mcp-server-axiom

61 starsOpen

Azure MCP

Azure/azure-mcp

1,219 starsOpen

Browserbase MCP

browserbase/mcp-server-browserbase

3,383 starsOpen

Chroma MCP

chroma-core/chroma-mcp

570 starsOpen

Browse

MCP servers by category

Other2643AI & ML2284Search2091Developer Tools1127Vector & Memory1121Cloud & DevOps721Files & Docs719Databases704Finance & Payments701Browser & Scraping485Communication418Productivity355