DokployMCP 使用教程

📖 项目简介

Dokploy 是开源、自托管的部署平台，装在你自己的服务器上。官方 MCP 包 @dokploy/mcp（Apache 协议，当前 0.29.3）把这个平台的全部接口交给 Codex：建项目、部署、绑域名、看日志、建数据库，都走同一套工具。

平台本身支持 Node、PHP、Python、Go、Ruby 等应用，原生 Docker Compose，自带 MySQL、PostgreSQL、MongoDB、MariaDB、libsql、Redis，以及备份、Traefik 路由、实时监控和部署通知。代码从 GitHub、GitLab、Gitea、Bitbucket 或任意 Git 地址拉，也可以直接跑镜像。

以前写完代码还要另开一个后台去点部署。接上 MCP 之后，写代码的那个 Codex 可以按同样的接口把上线做完。工具太多时用预设 deploy，只加载项目、环境、应用、Compose、域名和部署记录。

✨ 核心亮点

🚀

说完就能部署

应用、仓库、分支、构建，对应的都是 MCP 工具。

🌐

域名和证书

域名、路径、容器端口、证书可以一并交给它。

🗄️

数据库一起管

六种数据库的创建、启动、备份都在同一套接口里。

🎚️

工具可以瘦身

默认 508 个工具、49 类。预设 deploy 只留部署相关。

📊 能力速览

项目	说明
输入	Git 仓库、Docker 镜像、Docker Compose
适用类型	Web 应用、数据库、多服务项目
输出	运行中的应用、域名、部署记录和日志
语言 / 兼容	Node、PHP、Python、Go、Ruby；GitHub / GitLab / Gitea / Bitbucket
规格	官方 MCP 508 个工具、49 类；预设 all / minimal / core / deploy / databases / git

💻 环境要求

项目	要求
服务器	一台能 SSH 的 VPS，常见是 Ubuntu 或 Debian，已能跑 Docker
本机	Node.js 18 或更高（跑官方 MCP）；Codex 已登录
硬件	不需要独显。构建吃的是服务器 CPU 和内存
低配方案	先部署一个静态页或很小的 Node 服务，确认日志能刷完再上大项目
关键依赖	npx、Dokploy 后台里生成的 API Key。密钥在 Settings → Profile → API/CLI

🚀 如何使用

💡

先在服务器上装好面板并生成密钥，再把 MCP 接进 Codex。安装脚本的完整地址在上方「相关链接」里。

在服务器上安装面板

SSH 登录后执行官方安装脚本（命令在文首折叠块里）。装完用浏览器打开面板，注册管理员。

生成 API Key

进入 Settings → Profile → API/CLI，生成一把密钥。只在配置里填写，不要发到聊天记录或截图里。

接进 Codex

把「你的后台地址」换成面板地址（带 https），把「你的密钥」换成刚生成的 Key。建议加上 deploy 预设，避免一次塞进 508 个工具。

codex mcp add dokploy --env DOKPLOY_URL=你的后台地址 --env DOKPLOY_API_KEY=你的密钥 --env DOKPLOY_TOOL_PRESET=deploy -- npx -y @dokploy/mcp

确认接上了

打开 Codex，输入 /mcp。dokploy 一行显示 enabled 就可以开始说人话。

/mcp

让它部署

代码先推到 Git 仓库。然后直接说：

把这个仓库部署到我的服务器，分支用 main，构建完成后告诉我状态。

域名单独再说一句，并写明容器端口：

给这个应用绑上我的域名，容器端口按服务实际监听的端口填，证书用 Let's Encrypt。

预设怎么选

预设	适合
`deploy`	上线：项目、环境、应用、Compose、域名、部署记录
`minimal`	只建项目和改应用
`databases`	还要它帮你建库
`git`	要连 GitHub / GitLab 账号
`all`	全部 508 个工具。客户端吃力就不要用

进阶

数据库可以接着说「在这个项目里建一个 PostgreSQL」。部署失败就说「把最近一次部署日志拉出来，告诉我失败在哪一步」。通知可以接到 Telegram、Discord、Slack 或邮件。多台服务器用 Server 相关工具，不在第一天就开。

Windows 上如果 npx 起不来，配置里把命令改成 cmd，参数用 /c npx -y @dokploy/mcp。社区版 @vibetools/dokploy-mcp 默认只有 search、execute、list_profiles 三个工具，需要 Node 24，作为官方包的备选。

🎯 典型应用场景

🧪

个人项目上线

写完的小站从本地变成一个能打开的页面。

🔁

改完再发一版

推完代码再说一句重新部署，看部署记录。

🧱

带数据库的服务

应用和 PostgreSQL 放在同一个项目里。

📦

Compose 项目

多个容器的项目走 Compose 工具，不必拆开点。

👀

看失败日志

构建失败时让它拉日志，而不是自己翻面板。

🔔

部署结果通知

成功或失败推到 Telegram、Discord 或邮件。

📈 和同类比

	自己点面板	官方 MCP + Codex
部署	打开后台，填仓库，点 Deploy	说一句，走同一套接口
日志	自己切到 Deployments	让它把失败那次的日志读出来
工具数量	不占上下文	默认 508 个，建议预设 deploy
前提	面板已装好	同样要先有一台装好面板的服务器

✅

MCP 没有另做一套部署逻辑，工具是从面板的 OpenAPI 生成的。面板上能点的，接口里就有对应工具。

❓ 常见问题

Q: 和直接在面板上点有什么区别？

操作是同一套。差别是谁来点。MCP 把接口交给 Codex，你用中文说目标。

Q: 必须先有服务器吗？

要。它是自托管面板，本机只负责跑 MCP 客户端。没有装好的面板，Codex 没有地方可调。

Q: /mcp 里看不到它？

先跑 codex mcp list。后台地址要带 https，密钥不要多空格。Node 低于 18 时 npx 会起不来。工具太多导致超时，就改成 DOKPLOY_TOOL_PRESET=deploy 后重加一次。

Q: Windows 上报找不到命令？

用 cmd /c npx -y @dokploy/mcp。第一次拉包会慢，等它下完再看 /mcp。

Q: 部署失败怎么查？

让它读取最近一次部署日志。常见原因是分支名不对、构建命令不对、容器端口和应用监听端口不一致、仓库是私有的但没接 Git 账号。

Q: 域名打开是证书错误？

先确认域名已经解析到这台服务器，再在域名设置里选择 Let's Encrypt 并打开 HTTPS，等一两分钟。解析没生效时证书签不下来。

Q: 官方包和社区版怎么选？

默认用官方 @dokploy/mcp。社区版默认只有 3 个工具，上下文更省，需要 Node 24。两个都要自己的面板地址和密钥。

Q: 可以商用吗？

官方 MCP 是 Apache 协议，面板仓库是开源的。商用前自己再看一遍仓库里的许可证文件。密钥、服务器地址不要写进公开仓库。