dokploy-mcp-server

dokploy_compose

Create, deploy, update, and delete Docker Compose services, manage environment variables and networks, read logs, and control lifecycle actions in Dokploy.

Instructions

Manage Docker Compose services. create: name+environmentId. get: composeId (metadata + masked env summary — never values). update: composeId+fields (supports sourceType, composeFile for raw/inline, git source fields, autoDeploy, createEnvFile, serviceNetworks). delete/start/stop/getDefaultCommand: composeId. deploy: composeId, redeploy?, freshVolumes? (DESTRUCTIVE: runs docker compose down --volumes first, deleting the service's volume data; docker-compose type only, ignored for stack) (note: first deploy on new services may fail — retry immediately). move: composeId+targetEnvironmentId. loadServices: composeId (must deploy first). loadMounts: composeId+serviceName. saveEnvironment: composeId+env (full replace), createEnvFile? (also write a .env file next to the compose file). setEnvVars: composeId + set?/unset? (merge inside the server, masked confirmation only). getEnvKeys: composeId — KEY names only. getEnvValuesUnsafe: composeId — UNSAFE escape hatch that returns full KEY=VALUE pairs (output goes to the tool transcript). cancelDeployment/cleanQueues/killBuild/refreshToken: composeId. readLogs: composeId+containerId, tail?, since?, search?. search (as action): q|name|appName|description|projectId|environmentId + limit/offset. Note: the API's search index is narrower than the project tree — it can return fewer results than dokploy_project/dokploy_overview list, so use it to find a known service, not to inventory.

Input Schema

TableJSON Schema

Name	Required	Description
`q`	No	search: freeform query
`env`	No	Environment variables as KEY=VALUE pairs, one per line. Example: 'DB_HOST=localhost\nDB_PORT=5432'. Used by saveEnvironment (full replace).
`set`	No	setEnvVars: KEY=VALUE pairs to upsert, one per line.
`name`	No
`tail`	No	Number of recent log lines (default 100)
`type`	No
`limit`	No	search: max results (default 20)
`owner`	No	GitHub owner/organization
`since`	No	Time range: 'all' or a duration like '30m', '1h', '7d'
`title`	No
`unset`	No	setEnvVars: list of KEY names to remove.
`action`	Yes
`branch`	No	GitHub branch
`offset`	No	search: pagination offset
`search`	No	Filter log lines by substring
`appName`	No	Internal app name
`command`	No
`redeploy`	No
`serverId`	No
`composeId`	No
`projectId`	No	search: filter to a project
`autoDeploy`	No	Enable auto-deploy on git push
`repository`	No	GitHub repository (owner/repo format)
`sourceType`	No	Source type. github → set repository+owner+branch (+composePath). git → set customGitUrl+customGitBranch (+customGitSSHKeyId for private). raw → set composeFile (inline YAML). The API also supports gitlab/bitbucket/gitea sources, but those need provider-specific fields not yet exposed by this tool.
`composeFile`	No	Docker Compose YAML content (for sourceType: raw, set this to the inline compose file)
`composePath`	No	Path to compose file in repo
`composeType`	No	docker-compose or stack
`containerId`	No	Container ID for readLogs (use dokploy_docker findContainers to discover)
`description`	No
`serviceName`	No
`customGitUrl`	No	Custom git repository URL
`freshVolumes`	No	deploy: delete the service's volumes before deploying — destroys their data
`createEnvFile`	No	update/saveEnvironment: also write the env out to a .env file beside the compose file
`deleteVolumes`	No
`environmentId`	No
`customGitBranch`	No	Custom git branch
`serviceNetworks`	No	update: per-service Docker network attachments. All three fields are required per entry (see dokploy_network list for IDs).
`customGitSSHKeyId`	No	SSH key ID for private git repos
`deployDescription`	No
`targetEnvironmentId`	No

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedv1.10.0Oct 3, 2026

addedInput schema / properties / freshVolumes

Added value: +{
+  "description": "deploy: delete the service's volumes before deploying — destroys their data",
+  "type": "boolean"
+}

Changed2 schema fields changedv1.9.1Aug 26, 2026

addedInput schema / properties / createEnvFile

Added value: +{
+  "description": "update/saveEnvironment: also write the env out to a .env file beside the compose file",
+  "type": "boolean"
+}

addedInput schema / properties / serviceNetworks

Added value: +{
+  "description": "update: per-service Docker network attachments. All three fields are required per entry (see dokploy_network list for IDs).",
+  "items": {
+    "properties": {
+      "detachDokployNetwork": {
+        "type": "boolean"
+      },
+      "networkIds": {
+        "items": {
+          "type": "string"
+        },
+        "type": "array"
+      },
+      "serviceName": {
+        "type": "string"
+      }
+    },
+    "required": [
+      "serviceName",
+      "networkIds",
+      "detachDokployNetwork"
+    ],
+    "type": "object"
+  },
+  "type": "array"
+}

Changed5 schema fields changedv1.8.3Aug 9, 2026

changedInput schema / properties / action / enum

Previous value: -[
-  "create",
-  "get",
-  "update",
-  "delete",
-  "deploy",
-  "start",
-  "stop",
-  "move",
-  "loadServices",
-  "loadMounts",
-  "getDefaultCommand",
-  "cancelDeployment",
-  "cleanQueues",
-  "killBuild",
-  "refreshToken",
-  "saveEnvironment",
-  "setEnvVars",
-  "getEnvKeys",
-  "getEnvValuesUnsafe",
-  "readLogs"
-]New value: +[
+  "create",
+  "get",
+  "update",
+  "delete",
+  "deploy",
+  "start",
+  "stop",
+  "move",
+  "loadServices",
+  "loadMounts",
+  "getDefaultCommand",
+  "cancelDeployment",
+  "cleanQueues",
+  "killBuild",
+  "refreshToken",
+  "saveEnvironment",
+  "setEnvVars",
+  "getEnvKeys",
+  "getEnvValuesUnsafe",
+  "readLogs",
+  "search"
+]

addedInput schema / properties / limit

Added value: +{
+  "description": "search: max results (default 20)",
+  "maximum": 100,
+  "minimum": 1,
+  "type": "integer"
+}

addedInput schema / properties / offset

Added value: +{
+  "description": "search: pagination offset",
+  "maximum": 9007199254740991,
+  "minimum": 0,
+  "type": "integer"
+}

addedInput schema / properties / projectId

Added value: +{
+  "description": "search: filter to a project",
+  "type": "string"
+}

addedInput schema / properties / q

Added value: +{
+  "description": "search: freeform query",
+  "type": "string"
+}

Changed1 schema field changedv1.7.4Jun 29, 2026
- addedInput schema / additionalProperties
```
Added value: +false
```

Changed4 schema fields changedv1.7.3Jun 22, 2026

changedInput schema / properties / action / enum

Previous value: -[
-  "create",
-  "get",
-  "update",
-  "delete",
-  "deploy",
-  "start",
-  "stop",
-  "move",
-  "loadServices",
-  "loadMounts",
-  "getDefaultCommand",
-  "cancelDeployment",
-  "cleanQueues",
-  "killBuild",
-  "refreshToken",
-  "readLogs"
-]New value: +[
+  "create",
+  "get",
+  "update",
+  "delete",
+  "deploy",
+  "start",
+  "stop",
+  "move",
+  "loadServices",
+  "loadMounts",
+  "getDefaultCommand",
+  "cancelDeployment",
+  "cleanQueues",
+  "killBuild",
+  "refreshToken",
+  "saveEnvironment",
+  "setEnvVars",
+  "getEnvKeys",
+  "getEnvValuesUnsafe",
+  "readLogs"
+]

changedInput schema / properties / env / description

Previous value: -"Environment variables as KEY=VALUE pairs, one per line. Example: 'DB_HOST=localhost\\nDB_PORT=5432'"New value: +"Environment variables as KEY=VALUE pairs, one per line. Example: 'DB_HOST=localhost\\nDB_PORT=5432'. Used by saveEnvironment (full replace)."

addedInput schema / properties / set

Added value: +{
+  "description": "setEnvVars: KEY=VALUE pairs to upsert, one per line.",
+  "type": "string"
+}

addedInput schema / properties / unset

Added value: +{
+  "description": "setEnvVars: list of KEY names to remove.",
+  "items": {
+    "type": "string"
+  },
+  "type": "array"
+}

First observedv1.7.0May 29, 2026

TDQS

A4.5/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full burden and does so well: it discloses that deploy is DESTRUCTIVE (runs `docker compose down --volumes`, deletes volume data), that get returns a masked env summary, that getEnvValuesUnsafe is an unsafe escape hatch writing full secrets to the transcript, that saveEnvironment is a full replace, and that first deploy may fail and should be retried.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Dense but front-loaded: the general verb+resource leads, then action-by-action parameter requirements follow in a scannable run-on structure. Nearly every clause conveys actionable information, though the single-block paragraph format makes it harder to parse than a bulleted layout would.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 40-parameter, no-annotation, no-output-schema tool, the description covers destructive behavior, secret handling, action prerequisites, and return-value caveats (masked env, KEY-only vs KEY=VALUE). Coverage is strong; residual gaps are the handful of parameters undocumented anywhere.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is only 65% across 40 parameters, but the description compensates by mapping actions to their required fields and explaining semantics not in the schema (sourceType gitlab/bitbucket caveat, serviceNetworks requiring all three fields, redeploy/freshVolumes behavior). Some parameters (deleteVolumes, deployDescription, composeType) remain unexplained in both places.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Opens with a specific verb+resource ('Manage Docker Compose services') and then enumerates every supported action with its distinguishing inputs. This lets an agent distinguish it from siblings like dokploy_application and dokploy_deployment without opening the schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides per-action routing guidance and sequencing prerequisites (e.g. 'loadServices: must deploy first', search 'use it to find a known service, not to inventory'). It lacks an explicit comparison against sibling tools such as dokploy_application (when to pick compose vs application), so it falls short of a 5.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

dokploy_compose

Instructions

Input Schema

Schema Changelog

TDQS

Other Tools