dokploy-mcp

@wyattjoh/dokploy-mcp

MCP server that wraps the Dokploy REST API. Exposes Dokploy operations as Model Context Protocol tools for Claude Code, Claude Desktop, and other MCP clients.

Install

npm install -g @wyattjoh/dokploy-mcp

Or with Bun:

bun install -g @wyattjoh/dokploy-mcp

Configuration

The server supports two modes: single-instance and multi-instance. The two modes are mutually exclusive.

Single instance

Set a single Dokploy API token. All tools operate against one Dokploy server.

Variable	Required	Description
DOKPLOY_API_TOKEN	Yes	API token for your Dokploy instance
DOKPLOY_URL	No	Base URL (defaults to https://dokploy.wyattjoh.dev)

Multi-instance

Set per-instance tokens and URLs. Tools gain a required instance parameter so you can target different Dokploy servers from a single MCP session.

For each instance, define a pair of environment variables:

• DOKPLOY_<NAME>_API_TOKEN - API token for the instance
• DOKPLOY_<NAME>_URL - Base URL for the instance

Instance names are derived by lowercasing the <NAME> segment. Names must match [a-z0-9]([a-z0-9_]*[a-z0-9])?.

Example for two instances named prod and staging:

DOKPLOY_PROD_API_TOKEN=dkp_abc123
DOKPLOY_PROD_URL=https://dokploy.example.com
DOKPLOY_STAGING_API_TOKEN=dkp_def456
DOKPLOY_STAGING_URL=https://staging-dokploy.example.com

HTTP transport

By default the server uses stdio transport (for Claude Code and similar clients). Pass --http to start an HTTP server instead.

Variable	Required	Description
DOKPLOY_MCP_TOKEN	Yes (HTTP only)	Bearer token for authenticating MCP clients

dokploy-mcp --http --port 3000

The MCP endpoint is POST /mcp. A health check is available at GET /health.

MCP client configuration

Claude Code (.mcp.json)

Add to your project's .mcp.json or ~/.claude/.mcp.json:

Single instance:

{
  "mcpServers": {
    "dokploy": {
      "command": "dokploy-mcp",
      "env": {
        "DOKPLOY_API_TOKEN": "dkp_your_token_here",
        "DOKPLOY_URL": "https://dokploy.example.com"
      }
    }
  }
}

Multi-instance:

{
  "mcpServers": {
    "dokploy": {
      "command": "dokploy-mcp",
      "env": {
        "DOKPLOY_PROD_API_TOKEN": "dkp_prod_token",
        "DOKPLOY_PROD_URL": "https://dokploy.example.com",
        "DOKPLOY_STAGING_API_TOKEN": "dkp_staging_token",
        "DOKPLOY_STAGING_URL": "https://staging-dokploy.example.com"
      }
    }
  }
}

Using 1Password CLI (recommended)

Store your Dokploy API tokens in 1Password and use op run to inject them at runtime. This keeps secrets out of config files entirely.

1. Store each API token in 1Password (e.g., in a vault called Development)
2. Reference them with op:// URIs in your .mcp.json
3. Use op as the command so secrets are resolved in-memory

{
  "mcpServers": {
    "dokploy": {
      "command": "op",
      "args": ["run", "--", "dokploy-mcp"],
      "env": {
        "DOKPLOY_PROD_API_TOKEN": "op://Development/dokploy-prod/credential",
        "DOKPLOY_PROD_URL": "https://dokploy.example.com",
        "DOKPLOY_STAGING_API_TOKEN": "op://Development/dokploy-staging/credential",
        "DOKPLOY_STAGING_URL": "https://staging-dokploy.example.com"
      }
    }
  }
}

With this setup, op run resolves the op:// references and injects the real tokens into the subprocess environment. No plaintext secrets touch disk.

For HTTP transport with 1Password:

{
  "mcpServers": {
    "dokploy": {
      "command": "op",
      "args": ["run", "--", "dokploy-mcp", "--http"],
      "env": {
        "DOKPLOY_MCP_TOKEN": "op://Development/dokploy-mcp-token/credential",
        "DOKPLOY_PROD_API_TOKEN": "op://Development/dokploy-prod/credential",
        "DOKPLOY_PROD_URL": "https://dokploy.example.com"
      }
    }
  }
}

Tools

Projects

Tool	Description
dokploy_list_instances	List all configured Dokploy instances
dokploy_list_projects	List all projects

Applications