Dokploy MCP Server

Dokploy MCP Server exposes all Dokploy API endpoints as tools consumable via the Model Context Protocol (MCP). It allows MCP-compatible clients (e.g., AI models, other applications) to interact with your Dokploy server programmatically.

With 508 tools across 49 categories, this server provides complete coverage of the Dokploy API — from project and application management to databases, notifications, SSO, Docker, backups, and more.

Getting Started

Requirements

Bun >= v1.4.0 (or Docker)
Cursor, VS Code, Claude Desktop, or another MCP Client
A running Dokploy server instance

Install in Cursor

Go to: Settings -> Cursor Settings -> MCP -> Add new global MCP server

Add this to your Cursor ~/.cursor/mcp.json file. You may also install in a specific project by creating .cursor/mcp.json in your project folder. See Cursor MCP docs for more info.

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

Alternative: Use Bun

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

Alternative: Use Deno

{
  "mcpServers": {
    "dokploy-mcp": {
      "command": "deno",
      "args": ["run", "--allow-env", "--allow-net", "npm:@dokploy/mcp"],
      "env": {
        "DOKPLOY_URL": "https://your-dokploy-server.com",
        "DOKPLOY_API_KEY": "your-dokploy-api-token"
      }
    }
  }
}

Install in Windsurf

Add this to your Windsurf MCP config file. See Windsurf MCP docs for more info.

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

Install in VS Code

Add this to your VS Code MCP config file. See VS Code MCP docs for more info.

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

Install in Claude Code

Add the MCP server to Claude Code using the CLI:

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

Then set the environment variables in your .claude/settings.json or pass them inline:

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

Install in Zed

Add this to your Zed settings.json. See Zed Context Server docs for more info.

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

Install in Claude Desktop

Add this to your Claude Desktop claude_desktop_config.json file. See Claude Desktop MCP docs for more info.

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

Install in BoltAI

Open the "Settings" page of the app, navigate to "Plugins," and enter the following JSON:

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

Install in Opencode

Add this to your OpenCode configuration (located by default in ~/.config/opencode/opencode.json or opencode.json for local/project config). See Opencode MCP config for more info.

{
  "mcp": {
    "dokploy": {
      "type": "local",
      "command": ["npx", "-y", "@dokploy/mcp"],
      "environment": {
        "DOKPLOY_URL": "https://your-dokploy-server.com",
        "DOKPLOY_API_KEY": "your-dokploy-api-token"
      },
      "enabled": true
    }
  }
}

Using Docker

The Docker container supports both stdio and HTTP transport modes, making it flexible for different deployment scenarios.

Build the Docker Image:

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

Manual Docker Commands:

Stdio Mode (for MCP clients):

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

HTTP Mode (for web applications):

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

Docker Compose:

Use the provided docker-compose.yml for production deployments:

# Start HTTP service
docker-compose up -d dokploy-mcp-http

# View logs
docker-compose logs -f dokploy-mcp-http

MCP Client Configuration:

For stdio mode (Claude Desktop, VS Code, etc.):

{
  "mcpServers": {
    "dokploy-mcp": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "DOKPLOY_URL=https://your-dokploy-server.com",
        "-e",
        "DOKPLOY_API_KEY=your_token_here",
        "dokploy-mcp"
      ]
    }
  }
}

For HTTP mode (web applications):

Start the HTTP server first, then configure your client to connect to http://localhost:3000/mcp.

Install in Windows

The configuration on Windows is slightly different compared to Linux or macOS. Use cmd as the command wrapper:

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

Environment Variables

Variable	Required	Description
`DOKPLOY_URL`	Yes	Your Dokploy server URL (e.g., `https://your-dokploy-server.com`)
`DOKPLOY_API_KEY`	Yes	Your Dokploy API authentication token
`DOKPLOY_CUSTOM_HEADERS`	No	JSON object of additional upstream request headers. Header names and values must be strings. Reserved headers cannot be set here: `x-api-key`, `content-type`, `accept`.
`DOKPLOY_TOOL_PRESET`	No	Predefined toolset to load: `all` (default), `minimal`, `core`, `deploy`, `databases`, or `git`. Useful for clients/providers that struggle with very large tool lists.
`DOKPLOY_ENABLED_TAGS`	No	Comma-separated list of tags to filter which tools are loaded (e.g., `project,application,postgres`)
`DOKPLOY_DISABLED_TAGS`	No	Comma-separated list of tags to exclude from the selected toolset. Applied after `DOKPLOY_TOOL_PRESET` or `DOKPLOY_ENABLED_TAGS`.
`DOKPLOY_TIMEOUT`	No	Request timeout in milliseconds (default: `30000`)
`DOKPLOY_RETRY_ATTEMPTS`	No	Number of retry attempts (default: `3`)
`DOKPLOY_RETRY_DELAY`	No	Delay between retries in milliseconds (default: `1000`)
`DOKPLOY_REDACT_ENV`	No	Ignored. Secret values are always removed from tool results; `false` only logs a warning at startup. See Secrets never reach the model.
`DOKPLOY_REDACT_FIELDS`	No	Comma-separated extra field names to redact. They are added to the built-in list and cannot remove anything from it. A name matches a field when the field name ends with it, at any nesting depth, ignoring case, `_` and `-`. Built-in list: `env`, `buildArgs`, `buildSecrets`, `previewBuildSecrets`, `previewEnv`, `previewBuildArgs`, `password`, `currentPassword`, `appPassword`, `databasePassword`, `databaseRootPassword`, `redisPassword`, `mariadbPassword`, `mongoPassword`, `mysqlPassword`, `postgresPassword`, `registryPassword`, `token`, `accessToken`, `appToken`, `apiToken`, `botToken`, `refreshToken`, `metricsToken`, `secret`, `clientSecret`, `webhookSecret`, `githubClientSecret`, `githubWebhookSecret`, `apiKey`, `secretKey`, `secretAccessKey`, `accessKey`, `applicationKey`, `consumerKey`, `licenseKey`, `userKey`, `privateKey`, `privateKeyPass`, `encPrivateKey`, `encPrivateKeyPass`, `githubPrivateKey`, `sshKey`, `sshPrivateKey`, `customGitSSHKey`, `dockerAuth`, `authorization`, `cookie`, `credentials`, `connectionString`, `dsn`, `webhookUrl`.

For Dokploy instances behind Cloudflare Access or a similar reverse proxy, pass service-token headers with placeholder values like this:

DOKPLOY_CUSTOM_HEADERS='{"CF-Access-Client-Id":"your-client-id.access","CF-Access-Client-Secret":"your-client-secret"}'

Secrets never reach the model

The server removes secret values from every tool result and from its own log. This cannot be switched off.

Secret fields. The built-in field list above is redacted at any depth. A string becomes [REDACTED]; booleans, numbers, null, empty strings and values the panel has already hidden are kept, so flags such as secret: true stay readable. Variable lists (env, buildArgs, buildSecrets, docker Env) keep the variable names: NAME=[REDACTED].
Free text. Every other string is scrubbed: logs, compose files, Traefik and container files (base64 file content is decoded, scrubbed and encoded again; binary content is replaced), error text. Values of secret-looking names in NAME=value, key: value and JSON, URL passwords, Authorization and Bearer tokens, --password-style flags, well-known token formats and PEM private keys become [REDACTED]. Variable references such as ${VAR} and ${{project.VAR}} are kept; an inline default (${VAR:-default}) is redacted.
Blind env tools. env-keys lists variable names with secret and empty flags. env-apply changes single variables and never returns a value: set a value that is already known, generate a random secret on the server, copy a value from another service, remove a variable. A secret that only the user knows is entered in the Dokploy panel, not in the chat. Changes apply after a redeploy. Both tools, like superPassword-status, are loaded with every preset and tag filter. They need a Dokploy version that provides GET /env.keys and POST /env.apply.
No full-replace writes. Tools that need a whole env text (*-saveEnvironment, settings-writeTraefikEnv) are not listed. Every other tool rejects the fields env, buildArgs, buildSecrets, previewEnv, previewBuildArgs and previewBuildSecrets, because writing them would replace variables the model cannot see.
No write-back of redacted text. An input that contains [REDACTED] or the bare __DOKPLOY_REDACTED_SECRET__ is rejected.
Restorable tokens. In a compose file or a file mount the panel can hide a value behind a token of the form __DOKPLOY_REDACTED_SECRET__XXXXXXXXXXXX__. The server passes tokens through unchanged, and a token sent back where it was with compose-update (field composeFile) or mounts-update (field content) keeps the stored value: the panel restores it on save. Tokens are rejected in every other tool and field, must not be invented or altered, and cannot be mixed with [REDACTED] or the bare placeholder in the same text.
Errors. The body of a failed API response is never passed on. The model gets a fixed message per status.

The free-text scrubber works from names and formats. A secret stored in a file under a neutral name (FOO: value) is not recognised, so keep secrets in env variables and reference them.

An agent that also has SSH access to a server can read the same secrets from a shell. guard/ holds Claude Code hooks that block the usual ways this happens by accident (docker inspect, printenv, cat .env, database dumps to the terminal) and scrub the output of SSH MCP tools. They are not a security boundary; a restricted server account is.

Transport Modes

This MCP server supports multiple transport modes to suit different use cases:

Stdio Mode (Default)

The default mode uses stdio for direct process communication, ideal for desktop applications and command-line usage.

# Run with stdio (default)
npx -y @dokploy/mcp

HTTP Mode (Streamable HTTP + Legacy SSE)

Modern HTTP mode exposes the server via HTTP/HTTPS supporting both modern and legacy protocols for maximum compatibility:

Streamable HTTP (MCP 2025-03-26) - Modern protocol with session management
Legacy SSE (MCP 2024-11-05) - Backwards compatibility for older clients

# Run with HTTP mode
npx -y @dokploy/mcp --http
# or via environment variable
MCP_TRANSPORT=http npx -y @dokploy/mcp

Modern Streamable HTTP Endpoints:

Endpoint	Method	Description
`/mcp`	POST	Client-to-server requests
`/mcp`	GET	Server-to-client notifications (SSE)
`/mcp`	DELETE	Session termination
`/health`	GET	Health check

Legacy SSE Endpoints (Backwards Compatibility):

Endpoint	Method	Description
`/sse`	GET	SSE stream initialization
`/messages`	POST	Client message posting

Available Tools (508)

This MCP server provides 508 tools covering the entire Dokploy API, organized into 49 categories:

Core Resources

Category	Tools	Description
Project	8	Create, list, update, duplicate, search, and delete projects
Application	30	Full application lifecycle — create, deploy, redeploy, start, stop, build types, git providers (GitHub, GitLab, Bitbucket, Gitea), environment, Traefik config
Compose	29	Docker Compose management — create, deploy, templates, services, environment, isolated deployments
Domain	9	Domain CRUD, DNS validation, Traefik.me generation
Environment	7	Multi-environment support per project
Deployment	8	Deployment history, queue management, centralized view

Databases

Category	Tools	Description
PostgreSQL	15	Full lifecycle — create, deploy, start, stop, rebuild, passwords, external ports, environment
MySQL	15	Full lifecycle — create, deploy, start, stop, rebuild, passwords, external ports, environment
MariaDB	15	Full lifecycle — create, deploy, start, stop, rebuild, passwords, external ports, environment
MongoDB	15	Full lifecycle — create, deploy, start, stop, rebuild, passwords, external ports, environment
Redis	15	Full lifecycle — create, deploy, start, stop, rebuild, passwords, external ports, environment
LibSQL	13	Full lifecycle — create, deploy, start, stop, rebuild, external ports, environment

Infrastructure

Category	Tools	Description
Server	17	Multi-server management, metrics, security, monitoring setup
Docker	9	Container management — list, restart, remove, upload files, inspect config
Cluster / Swarm	8	Swarm node management, container stats, cluster operations
Settings	51	Server settings, Traefik config, Docker cleanup, GPU, monitoring, Redis, disk usage
Registry	7	Docker registry management and testing

Security & Auth

Category	Tools	Description
SSO	10	Single sign-on providers, trusted origins
SSH Keys	7	SSH key management — create, generate, list, update, remove
Certificates	5	SSL/TLS certificate management
Security	4	Basic auth and security rules per application
Custom Roles	6	Role-based access control with custom permissions
User	23	User management, permissions, API keys, invitations, metrics
Organization	11	Multi-org support, invitations, member roles

Operations

Category	Tools	Description
Backup	12	Database backups — Postgres, MySQL, MariaDB, MongoDB, LibSQL, Compose, WebServer
Volume Backups	6	Volume-level backup scheduling and management
Destination	6	S3-compatible backup destinations (AWS, Cloudflare R2, etc.)
Schedule	6	Scheduled tasks — cron-based automation
Notification	41	Multi-channel alerts — Slack, Discord, Telegram, Email, Teams, Gotify, Ntfy, Pushover, Lark, Mattermost, Resend, Custom webhooks
Rollback	2	Application rollback management

Other

Category	Tools	Description
AI	9	AI-powered suggestions, model management
Git Providers	27	GitHub, GitLab, Gitea, Bitbucket — branches, repos, connection testing
Tag	8	Project tagging and bulk assignment
Patch	12	File patching system for applications
Mounts	6	Volume and bind mount management
Port	4	Port mapping configuration
Redirects	4	URL redirect rules
Preview Deployments	4	PR preview deployment management
Stripe	7	Billing and subscription management
License Key	6	Enterprise license management
Whitelabeling	4	Custom branding for enterprise
Audit Log	1	Activity audit trail
Admin	1	Admin-level monitoring setup

Tool Filtering

By default, the server exposes all Dokploy API tools. Some MCP clients and LLM providers can be slower or less reliable when very large tool lists are sent to the model. You can reduce the loaded tools with presets or tag filters.

Use DOKPLOY_TOOL_PRESET for common workflows:

Preset	Included tags
`all`	All tools (default)
`minimal`	`project`, `application`
`core`	`project`, `server`, `application`
`deploy`	`project`, `environment`, `server`, `application`, `compose`, `domain`, `deployment`
`databases`	`postgres`, `redis`, `mysql`, `mariadb`, `mongo`, `libsql`
`git`	`github`, `gitlab`, `bitbucket`, `gitea`, `gitProvider`, `registry`, `sshKey`

# Recommended starting point for clients/providers sensitive to large toolsets
DOKPLOY_TOOL_PRESET=minimal

For exact control, set DOKPLOY_ENABLED_TAGS:

# Only load project, application, and postgres tools
DOKPLOY_ENABLED_TAGS=project,application,postgres

You can also remove categories from a preset:

DOKPLOY_TOOL_PRESET=core
DOKPLOY_DISABLED_TAGS=postgres,redis

If DOKPLOY_ENABLED_TAGS is set, it takes precedence over DOKPLOY_TOOL_PRESET. DOKPLOY_DISABLED_TAGS is applied last.

All tools include semantic annotations (readOnlyHint, destructiveHint, idempotentHint) to help MCP clients understand their behavior and safety characteristics.

Architecture

Built with @modelcontextprotocol/sdk, TypeScript, and Zod for type-safe schema validation:

508 Tools covering the entire Dokploy API
Multiple Transports: Stdio (default) and HTTP (Streamable HTTP + legacy SSE)
Auto-generated Tools: Tools are generated from the Dokploy OpenAPI spec via bun run generate:all
Tool Filtering: Load only the categories you need via DOKPLOY_ENABLED_TAGS
Robust Error Handling: Centralized API client with interceptors and retry logic
Type Safety: Full TypeScript with Zod schema validation
Tool Annotations: Semantic hints for MCP client behavior understanding

Development

Clone the project and install dependencies:

git clone https://github.com/Dokploy/mcp.git
cd mcp
bun install

Build:

bun run build

Regenerate tools from the Dokploy OpenAPI spec:

bun run generate:all

Local Configuration Example

{
  "mcpServers": {
    "dokploy-mcp": {
      "command": "bun",
      "args": ["/path/to/mcp/src/index.ts"],
      "env": {
        "DOKPLOY_URL": "https://your-dokploy-server.com",
        "DOKPLOY_API_KEY": "your-dokploy-api-token"
      }
    }
  }
}

Testing with MCP Inspector

npx -y @modelcontextprotocol/inspector npx @dokploy/mcp

Troubleshooting

MCP Client Errors

Try adding @latest to the package name.
Make sure you are using Bun v1.4 or higher; the server runs on the Bun runtime.
Verify your DOKPLOY_URL and DOKPLOY_API_KEY environment variables are correctly set.
If too many tools are loading or your provider times out while processing tools, start with DOKPLOY_TOOL_PRESET=minimal, then use DOKPLOY_ENABLED_TAGS for exact category filtering if needed.

Contributing

We welcome contributions! If you'd like to contribute to the Dokploy MCP Server, please check out our Contributing Guide.

Support

If you encounter any issues, have questions, or want to suggest a feature, please open an issue in our GitHub repository.

License

This project is licensed under the Apache License.

Name		Name	Last commit message	Last commit date
.github/workflows		.github/workflows
guard		guard
scripts		scripts
src		src
.dockerignore		.dockerignore
.env.example		.env.example
.gitignore		.gitignore
CONTRIBUTING.md		CONTRIBUTING.md
Dockerfile		Dockerfile
LICENSE		LICENSE
README.md		README.md
TOOLS.md		TOOLS.md
biome.json		biome.json
bun.lock		bun.lock
docker-compose.yml		docker-compose.yml
openapi.json		openapi.json
package.json		package.json
tsconfig.json		tsconfig.json

Latest commit

History

Folders and files

Repository files navigation

Dokploy MCP Server

Getting Started

Requirements

Install in Cursor

Install in Windsurf

Install in VS Code

Install in Claude Code

Install in Zed

Install in Claude Desktop

Install in BoltAI

Install in Opencode

Using Docker

Install in Windows

Environment Variables

Secrets never reach the model

Transport Modes

Stdio Mode (Default)

HTTP Mode (Streamable HTTP + Legacy SSE)

Available Tools (508)

Core Resources

Databases

Infrastructure

Security & Auth

Operations

Other

Tool Filtering

Architecture

Development

Local Configuration Example

Testing with MCP Inspector

Troubleshooting

MCP Client Errors

Contributing

Support

License

About

Resources

Contributing

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages