@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

Tool	Description
dokploy_list_applications	List all applications (filtered from projects)
dokploy_get_application	Get full application config by ID
dokploy_update_application	Update application config fields
dokploy_deploy	Trigger a deployment
dokploy_start_application	Start an application
dokploy_stop_application	Stop an application

Compose

Tool	Description
dokploy_get_compose	Get compose stack config by ID
dokploy_deploy_compose	Deploy a compose stack
dokploy_redeploy_compose	Redeploy a compose stack
dokploy_start_compose	Start a compose stack
dokploy_stop_compose	Stop a compose stack
dokploy_update_compose	Update compose stack config
dokploy_list_compose_services	List services in a compose stack
dokploy_list_compose_deployments	List deployments for a compose stack
dokploy_list_compose_domains	List domains for a compose stack

Deployments

Tool	Description
dokploy_list_deployments	List deployments for an application

Domains

Tool	Description
dokploy_list_domains	List domains for an application
dokploy_create_domain	Add a domain to an application

Environment

Tool	Description
dokploy_list_environment	List environment variables for an application
dokploy_update_environment	Set environment variables (merge with existing)
dokploy_delete_environment	Remove environment variables by key

Build

Tool	Description
dokploy_save_build_type	Update build configuration
dokploy_save_github_provider	Update GitHub source configuration

Operational

Tool	Description
dokploy_get_containers	List Docker containers
dokploy_get_app_monitoring	Get application monitoring data
dokploy_redeploy_application	Redeploy an application
dokploy_cancel_deployment	Cancel a running deployment
dokploy_kill_build	Kill a running build
dokploy_get_version	Get the Dokploy server version
dokploy_list_servers	List all configured servers

Development

bun install
bun run start              # stdio transport
bun run start:http         # HTTP transport on port 3000
bun run build              # transpile to dist/ (Node.js target)
bun run lint               # oxlint
bun run typecheck          # tsc --noEmit

License

MIT