dokploy-api-mcp

Dokploy 部署

在可自托管的 Dokploy 实例上部署和管理应用（v0.28+，已测试至 v0.29.x）。 Dokploy 是一个开源 PaaS（Vercel/Heroku 的替代方案），使用 Docker + Traefik v3。

DOKPLOY_URL 末尾不能包含 /api。 MCP 服务会自行追加 /api；如果基础 URL 以 /api 结尾，所有请求都会发送到 /api/api/...，导致调用全部失败。请使用 https://dokploy.example.com。

快速参考

项目	值
控制面板	https://<DOKPLOY_HOST>/
API 基础地址	https://<DOKPLOY_HOST>/api/
Swagger UI	https://<DOKPLOY_HOST>/swagger（需要在浏览器中登录）
认证请求头	x-api-key: <TOKEN>
CLI 安装	npm install -g @dokploy/cli
MCP 服务	@sattva/dokploy-mcp（完整 API 覆盖；Dokploy v0.29.x 上约有 540 个工具）
API 版本	OpenAPI 3.1.0；工具数量取决于 Dokploy 版本（v0.28.4 有 449 个，v0.29.8 有 539 个）
文档	https://docs.dokploy.com

首次运行 — 设置

首次使用时，请检查是否已配置 Dokploy MCP 服务。如果没有，请运行交互式设置：

1. Check: is a "dokploy" MCP server configured? (`claude mcp list`)
2. If NO → run: python3 skills/dokploy-api-mcp/scripts/setup.py
   (or the full path in the user's skill installation directory)
3. The script will:
   - Ask for the Dokploy URL (e.g., https://dokploy.example.com — without /api)
   - Ask for the API key (Dashboard → Settings → Profile → API/CLI)
   - Validate the connection and report how many endpoints the instance exposes
   - Ask which tool surface to use (tools / gateway / both)
   - Register the server via `claude mcp add-json`, or print the JSON to paste
     manually if the CLI is unavailable
4. Tell the user: "Restart Claude Code to activate the Dokploy MCP server."

使用 CLI 参数（非交互式）：

python3 skills/dokploy-api-mcp/scripts/setup.py --url https://dokploy.example.com --key YOUR_API_KEY --mode gateway

仅当实例使用自签名证书时才添加 --insecure — 这会禁用 TLS 验证，之后 API 密钥将通过未经验证的连接传输。

完成设置后，重启 Claude Code 后即可使用 MCP 服务（@sattva/dokploy-mcp，约有 540 个工具）。所有操作都应优先使用 MCP 工具，而非 curl。

环境变量

使用此技能前，请确保以下变量可用：

DOKPLOY_URL=https://dokploy.example.com
DOKPLOY_API_KEY=<generated-api-token>

生成 API 令牌：控制面板 → Settings → Profile → API/CLI → Generate。

部署工作流

步骤 1：检查当前状态

# Get application status
curl -s -X GET "${DOKPLOY_URL}/api/trpc/application.one?input=$(python3 -c "
import urllib.parse, json
print(urllib.parse.quote(json.dumps({'json':{'applicationId':'APP_ID'}})))
")" -H "x-api-key: ${DOKPLOY_API_KEY}"

步骤 2：触发部署

# Deploy application (POST — mutation)
curl -s -X POST "${DOKPLOY_URL}/api/application.deploy" \
  -H "x-api-key: ${DOKPLOY_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{"json":{"applicationId":"APP_ID"}}'

步骤 3：监控部署状态

# Poll deployment status
curl -s -X GET "${DOKPLOY_URL}/api/trpc/deployment.all?input=$(python3 -c "
import urllib.parse, json
print(urllib.parse.quote(json.dumps({'json':{'applicationId':'APP_ID'}})))
")" -H "x-api-key: ${DOKPLOY_API_KEY}"

步骤 4：验证运行状况

curl -sk "https://<app-domain>/api/health"

API 参考

Dokploy 内部使用 tRPC。有两种请求格式：

查询（读取）— 使用编码后的输入发送 GET 请求

GET /api/trpc/<router>.<procedure>?input=URL_ENCODED({"json":{...}})
Header: x-api-key: <token>

变更（写入）— 使用 JSON 请求体发送 POST 请求

POST /api/<router>.<procedure>
Header: x-api-key: <token>
Header: Content-Type: application/json
Body: {"json":{...}}

主要端点

完整列表请参阅 references/API-REFERENCE.md（基于 v0.28.4；运行 settings.getOpenApiDocument 可获取你所用实例的实际端点列表）。

端点	方法	用途
project.all	GET	列出所有项目
project.one	GET	按 ID 获取项目
application.one	GET	获取应用详情和状态
application.deploy	POST	触发部署
application.stop	POST	停止应用
application.start	POST	启动应用
application.update	POST	更新应用设置
application.saveBuildType	POST	更改构建类型
application.saveEnvironment	POST	设置环境变量
compose.one	GET	获取 Compose 服务
compose.deploy	POST	部署 Compose 服务
deployment.all	GET	列出应用的部署记录
domain.byApplicationId	GET	获取应用的域名
domain.create	POST	添加自定义域名
postgres.one	GET	获取 PostgreSQL 服务
redis.one	GET	获取 Redis 服务
mariadb.one	GET	获取 MariaDB 服务
mongo.one	GET	获取 MongoDB 服务
environment.byProjectId	GET	列出环境
rollback.rollback	POST	回滚部署
schedule.create	POST	创建计划任务
backup.create	POST	创建备份配置
notification.createTelegram	POST	设置 Telegram 通知
docker.getContainersByAppNameMatch	GET	列出 Docker 容器
application.readTraefikConfig	GET	读取 Traefik 配置

CLI 用法

# Install
npm install -g @dokploy/cli

# Authenticate (creates ~/.config/dokploy/config.json)
dokploy authenticate

# Verify token
dokploy verify

# Application management
dokploy app create   # Create new application
dokploy app deploy   # Deploy application
dokploy app stop     # Stop application
dokploy app delete   # Delete application

# Database management
dokploy db create    # Create database service
dokploy db delete    # Delete database service

# Environment variables
dokploy env set      # Set env vars
dokploy env list     # List env vars

# Project management
dokploy project create
dokploy project list

MCP 服务（完整 API 覆盖，约有 540 个工具）

MCP 可用时，务必优先使用 MCP 工具，而非 curl。 MCP 会自动处理 tRPC URL 编码和响应解析。

完整工具参考请参阅 references/MCP-TOOLS.md。

服务行为（v1.1.0+）

• 安全标注：GET 工具带有 readOnlyHint，会修改数据的动词（deploy/delete/stop/update/...）带有 destructiveHint — 客户端可以突出显示或限制危险调用。
• 响应为紧凑 JSON，超过 DOKPLOY_MAX_RESPONSE_CHARS（默认值为 50000）时会截断，并添加 _truncated 标记 — 应改进查询，而不是盲目提高上限。
• 请求会超时，超时时间由 DOKPLOY_TIMEOUT_MS 控制（默认值为 30s）；GET 遇到 5xx/429 时会重试。
• OpenAPI 规范会缓存在 OS 临时目录中 — 即使 Dokploy 暂时无法访问，服务也能继续运行。

网关模式（v1.2.0+）— 4 个工具，而不是 540 个

在服务的 env 中设置 DOKPLOY_MODE=gateway，即可用 4 个工具取代每个端点对应的工具：

工具	用途
dokploy_search(query)	按关键词查找端点
dokploy_describe(endpoint)	获取单个端点的参数架构
dokploy_call(endpoint, params)	调用只读（GET）端点
dokploy_mutate(endpoint, params)	调用写入端点 — 有破坏性

流程：搜索 → 描述 → 调用/修改。实测开销：tools/list 为 2.7 KB，而非 239 KB（−98.9%）；完整的发现并调用流程约为 0.8k 个 token。每个工具都会在发起任何请求前拒绝类型不匹配的端点，因此读写区分依然有效 — 这就是为什么有 4 个工具，而不是一个通用的 call。

广泛探索时使用网关模式；如果每次都使用相同的少数几个端点，请使用 tools 模式（默认模式）或 DOKPLOY_TOOLS 配置。DOKPLOY_MODE=both 会同时启用两种模式。

推荐：筛选工具集

完整列表约有 540 个工具（tools/list 约占 60k 个 token）。日常部署时，请在 env 块中设置配置：

"DOKPLOY_TOOLS": "project_*,application_*,compose_*,deployment_*,docker_*,domain_*,postgres_*,redis_*,backup_*,rollback_*,schedule_*,settings_health"

这样可将负载减少约 70%，同时仍能满足所有常规工作需求。DOKPLOY_READONLY=1 会启用安全的只监控配置（仅 GET 工具）。

设置

自动设置（推荐）：运行上方“首次运行”部分中的设置脚本 — 它会自动配置 MCP。

手动设置 — 将以下内容添加到 Claude 配置的 mcpServers 对象中（Claude Code 使用 ~/.claude.json；也可通过 claude mcp add-json 自动添加）：

{
  "mcpServers": {
    "dokploy": {
      "type": "stdio",
      "command": "cmd",
      "args": ["/c", "npx", "-y", "@sattva/dokploy-mcp@latest"],
      "env": {
        "DOKPLOY_URL": "https://dokploy.example.com",
        "DOKPLOY_API_KEY": "<your-api-token>",
        "DOKPLOY_MODE": "gateway"
      }
    }
  }
}

注意： DOKPLOY_URL 不带 /api 后缀 — 请参阅顶部的警告。 注意： 在 macOS/Linux 上使用 "command": "npx", "args": ["-y", "@sattva/dokploy-mcp@latest"]。 本地开发： "command": "node", "args": ["<path>/dokploy-mcp/dist/index.js"]。 环境变量： DOKPLOY_MODE（tools/gateway/both）、DOKPLOY_TOOLS、DOKPLOY_READONLY、 DOKPLOY_TIMEOUT_MS、DOKPLOY_MAX_RESPONSE_CHARS。

按类别划分的 MCP 工具（统计数据来自 Dokploy v0.28.4；v0.29.x 还新增了约 90 个工具：ai_*、forwardAuth_*、customRole_*、whitelabeling_*、patch_* 等）

类别	工具数	描述
application_*	29	应用生命周期、部署、配置、Git 提供商
compose_*	28	Docker Compose 服务
settings_*	49	服务设置、Traefik、清理、监控
notification_*	38	Slack/Telegram/Discord/Email/Webhook/Gotify/Ntfy/Pushover/Lark/Teams
user_*	18	用户管理、API 密钥、权限
server_*	16	远程服务管理
postgres_*	14	PostgreSQL 管理
redis_*	14	Redis 管理
mysql_*	14	MySQL 管理
mariadb_*	14	MariaDB 管理
mongo_*	14	MongoDB 管理
patch_*	12	文件补丁
backup_*	11	数据库备份
organization_*	10	组织、邀请
sso_*	10	SSO/SAML 企业身份验证
domain_*	9	域名/SSL 管理
ai_*	9	AI 驱动的 Compose 生成器
deployment_*	8	部署历史、队列
project_*	8	项目管理
gitea_*	8	Gitea 提供商
docker_*	7	容器操作
bitbucket_*	7	Bitbucket 提供商
registry_*	7	Docker 镜像仓库
gitlab_*	7	GitLab 提供商
stripe_*	7	账单（云端）
environment_*	7	每个项目的环境
github_*	6	GitHub 提供商
licenseKey_*	6	企业许可
sshKey_*	6	SSH 密钥管理
mounts_*	6	卷挂载
destination_*	6	S3 备份目标
schedule_*	6	计划任务/cron
volumeBackups_*	6	卷备份
certificates_*	4	SSL 证书
cluster_*	4	Docker Swarm 集群
port_*	4	端口管理
redirects_*	4	URL 重定向
security_*	4	安全设置
previewDeployment_*	4	预览部署
swarm_*	3	Swarm 节点信息
gitProvider_*	2	通用 Git 提供商
rollback_*	2	部署回滚
admin_*	1	管理员设置

MCP 部署工作流

1. application_one                → check current status
2. application_saveEnvironment    → set/update env vars if needed
3. application_saveBuildType      → ensure Dockerfile build configured
4. application_deploy             → trigger deployment
5. application_one                → poll until applicationStatus = "done"
6. curl health endpoint           → verify app is working

日志——可通过 MCP 获取（v0.29.x）

日志并非只能通过 Dashboard 获取。已在 v0.29.8 上验证，所有工具均为只读：

工具	返回内容
deployment_readLogs(deploymentId)	单次部署的构建/部署日志
application_readLogs(applicationId)	应用容器日志
compose_readLogs(composeId, containerId)	单个 Compose 容器的日志
postgres_readLogs / mysql_readLogs / mariadb_readLogs / mongo_readLogs / redis_readLogs	数据库服务日志

典型流程：deployment_all(applicationId) → 获取最新的 deploymentId → deployment_readLogs。只有实时流式传输仍仅支持 WebSocket；需要实时观察构建时，请使用 Dashboard。

MCP 的剩余限制

• 通过 Docker exec 进入容器——没有 API 端点，请通过 SSH 连接 VPS

其他所有功能都可通过 MCP 工具使用，包括：Redis、MariaDB、MongoDB、Compose、备份、通知、计划任务、回滚、SSO、补丁、组织等。

常见问题

详细解决方案请参阅 references/PITFALLS.md。

问题	原因	解决方法
每次 MCP 调用都返回 404	DOKPLOY_URL 以 /api 结尾 → 请求会发往 /api/api/...	删除 /api 后缀
COPY /app/public 失败	Git 会忽略空目录	在 Dockerfile 中添加 RUN mkdir -p public
数据库连接错误	Neon HTTP 驱动与标准 PG 不兼容	使用 postgres（postgres.js）包
缺少 Clerk publishableKey	SSG 会在构建时验证环境变量	使用 export const dynamic = "force-dynamic"，并在构建阶段跳过 provider
容器因 migrate.mjs 崩溃	standalone 输出缺少模块	通过应用内 API 端点运行迁移
需要构建日志	—	使用 deployment.readLogs(deploymentId)；仅支持通过 WebSocket 实时流式传输
需要容器日志	—	使用 application.readLogs / compose.readLogs / <db>.readLogs
无法访问外部数据库端口	VPS 防火墙阻止了该端口	使用内部 Docker 网络名称
curl 返回 SSL 证书错误	使用了自签名证书，或 Let's Encrypt 证书签发延迟	使用 curl -sk，或等待证书签发
部署后 API 路由返回 404	路由未包含在 standalone 输出中	确认路由存在于 .next/standalone 中
升级后 Traefik 中间件异常	Dokploy v0.25+ 使用 Traefik v3	更新中间件配置语法

构建类型

Dokploy 支持：

类型	适用场景
Dockerfile	自定义构建、多阶段构建、完全控制
Nixpacks	自动检测语言，无需配置
Buildpack	与 Heroku/Paketo 兼容的应用
Docker Image	来自镜像仓库的预构建镜像

服务（数据库）

通过 Dashboard → Project → Add Service 创建：

• PostgreSQL — 内部主机名：<appName>:5432
• MySQL/MariaDB — 内部主机名：<appName>:3306
• MongoDB — 内部主机名：<appName>:27017
• Redis — 内部主机名：<appName>:6379

内部主机名使用 Docker 网络。外部端口为可选项（可能需要配置防火墙规则）。

域名与 SSL

1. 通过 Dashboard 或 API（domain.create）添加域名
2. 将 DNS A 记录指向 VPS IP
3. Dokploy 通过 Traefik v3 自动签发 Let's Encrypt 证书
4. DNS 传播完成后，HTTPS 会自动生效

Next.js 专用指南

Next.js 14/15 部署到 Dokploy 的完整详情，请参阅 references/NEXTJS-GUIDE.md。