Plesk Deploy

plesk-deploy-mcp

一个 MCP 服务，可帮助任何 AI Agent（Claude Code、Claude Desktop、Cursor、VS Code 等）为 Plesk 服务设置并运行安全部署。部署流程如下：

1. GitHub Actions 测试项目并构建发布包。
2. 由人员审批。
3. 服务上的小型发布管理器将发布包解压到新的发布文件夹，备份数据库，执行迁移，原子切换并检查运行状况。
4. 如果新版本运行状况不佳，它会自动回滚。

该服务封装了经过生产环境验证的工作流。它会检查你的项目，将整套部署工具包生成为差异内容供你审核，并对其进行验证。启用 SSH 工具后，它还可以通过你自己的 SSH 读取部署状态和日志，并执行回滚。

与 Plesk 或 WebPros 无关联，也未获得其认可。

目录

• 它如何保障生产环境安全
• 安装
• 启用 SSH 工具
• 使用方法
• 工具
• 资源和提示词
• 配置
• 常见问题

它如何保障生产环境安全

• 不会有任何机密信息经由此服务传递。
  • 没有工具会接收或返回密钥、密码或令牌。
  • SSH 使用系统自带的 ssh、~/.ssh/config 中的别名、ssh-agent 和 known_hosts。
  • 环境文件只读取变量名称，绝不会打开真实的 .env 文件。
  • 每个结果都会经过扫描，任何疑似机密信息的内容都会被隐藏。
• 不会从你的笔记本电脑部署。 部署始终在 GitHub Actions 中运行，并由 production 环境进行审批。没有任何工具会构建、上传或部署。
• 只有指定可访问的主机后，SSH 工具才会启用，主机需在 PLESK_DEPLOY_SSH_HOSTS 中列出。
• SSH 工具只运行固定命令。 它们只会运行固定列表中的只读发现命令，或发布管理器自带的 --status、--log 和 --rollback。没有“运行此命令”工具。
• 每个输入在写入文件或命令行之前都会根据严格模式进行检查，之后还会进行 shell 转义。
• 始终严格检查主机密钥（StrictHostKeyChecking=yes），并始终关闭代理转发。你自己的配置无法放宽这些限制。
• 默认以试运行方式生成工具包。
  • 只有设置 write: true 时才会写入，且写入位置仅限你的 git 仓库内，绝不会通过符号链接写入。
  • 绝不会删除任何内容。
  • 除非你在 overwrite 中列出某个文件，否则绝不会替换该文件。
• 回滚需要精确确认： confirm: "<app>@<host>"。回滚过程绝不会中途被打断。
• 不收集遥测数据。 唯一的网络流量是到你指定主机的 SSH 流量，以及你查询运行状态时访问 api.github.com 的流量。

详情请参阅威胁模型和隐私政策。

安装

你需要 Node.js 22 或更高版本，但 Claude Desktop 自带 Node.js。

Claude Code

claude mcp add --transport stdio --scope user plesk-deploy -- npx -y plesk-deploy-mcp

启用 SSH 工具并使用别名 myserver（见下文）：

claude mcp add --env PLESK_DEPLOY_SSH_HOSTS=myserver --transport stdio --scope user plesk-deploy -- npx -y plesk-deploy-mcp

使用 claude mcp list 检查（应显示 ✔ Connected），也可以在会话中使用 /mcp。

也可以作为插件使用。 它同时包含服务和 plesk-deploy 技能；当你谈到向 Plesk 部署时，该技能会自动加载：

/plugin marketplace add usama-saeed831/plesk-deploy-mcp
/plugin install plesk-deploy@plesk-deploy-mcp

随后 Claude Code 会询问允许使用的 SSH 主机别名（留空即可关闭 SSH 工具），以及可选的只读 GitHub 令牌；该令牌会作为机密信息存储。

Claude Desktop

**作为扩展：**从 releases 下载 plesk-deploy-mcp-<version>.mcpb，然后前往 Settings → Extensions → Advanced settings → Install Extension… 并选择该文件。扩展的设置可让你输入允许使用的 SSH 主机别名和可选的只读 GitHub 令牌。

或在 claude_desktop_config.json 中（Settings → Developer → Edit Config）：

{
  "mcpServers": {
    "plesk-deploy": {
      "command": "npx",
      "args": ["-y", "plesk-deploy-mcp"],
      "env": { "PLESK_DEPLOY_SSH_HOSTS": "myserver" }
    }
  }
}

Cursor

在 ~/.cursor/mcp.json（所有项目）或 .cursor/mcp.json（单个项目）中：

{
  "mcpServers": {
    "plesk-deploy": {
      "command": "npx",
      "args": ["-y", "plesk-deploy-mcp"],
      "env": { "PLESK_DEPLOY_SSH_HOSTS": "myserver" }
    }
  }
}

VS Code

运行：

code --add-mcp '{"name":"plesk-deploy","type":"stdio","command":"npx","args":["-y","plesk-deploy-mcp"]}'

或将其添加到 .vscode/mcp.json：

{
  "servers": {
    "plesk-deploy": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "plesk-deploy-mcp"],
      "env": { "PLESK_DEPLOY_SSH_HOSTS": "myserver" }
    }
  }
}

在任何客户端中，省略 env 即可关闭 SSH 工具。本地工具无需这些设置即可使用。

启用 SSH 工具

1. 在 ~/.ssh/config 中添加主机别名。最安全的账户是 server-setup.sh 创建的部署账户：它唯一的 sudo 权限是使用发布管理器，因此可以读取状态和日志并回滚，除此之外不能做任何事。

   Host myserver
     HostName 203.0.113.10
     User myapp-deploy
     IdentityFile ~/.ssh/myapp_deploy
     IdentitiesOnly yes
   

2. 亲自连接一次（ssh myserver）。接受主机密钥之前，请将其指纹与服务器上运行 ssh-keygen -lf /etc/ssh/ssh_host_ed25519_key.pub 的输出进行比较。此服务器绝不会替你添加主机密钥。

3. 在 PLESK_DEPLOY_SSH_HOSTS 中列出该别名（以逗号分隔），然后重启 MCP 服务。

如果密钥有口令，请将其加载到 ssh-agent（ssh-add）中。服务绝不会提示输入密码或口令。

使用方法

向你的 Agent 提出请求：

为这个项目设置 Plesk 部署。

也可以直接启动提示词。在 Claude Code 中，/mcp__plesk-deploy__setup-plesk-deployment 会引导你完成 8 个阶段：

1. 检查项目
2. 只读检查服务器
3. 选择部署模式
4. 与你商定计划
5. 生成并验证工具包
6. 移交手动操作步骤（服务器、Plesk、GitHub）
7. 验证首次部署并进行回滚演练
8. 编写文档

在任何操作影响生产环境之前，Agent 都会暂停并征求你的同意。它会告诉你每个密钥应放在哪里，并且绝不会向你索要密钥。

你还可以提出其他请求：

• “检查这个项目，并展示它的部署信息。”
• “myserver 上的 acme 应用当前运行的是什么版本，最近一次部署日志写了什么？”
• “回滚 myserver 上的 acme。”Agent 会展示哪些内容将成为当前运行版本，并先征求你的确认。
• “me/acme 中最近一次 Deploy to Plesk 是否成功？是否正在等待批准？”

工具

工具	功能	是否会更改内容？
inspect_project	项目的部署信息表	否
server_discovery_commands	供你在服务器上运行的只读命令	否
generate_deploy_kit	生成部署工具包；默认进行试运行	仅限 write: true 时
validate_deploy_kit	检查工具包并运行发布管理器的测试	否（在临时文件夹中运行）
server_discover	通过 SSH 运行相同的只读命令	否
deploy_status	服务器上的发布版本及当前运行的版本	否
deploy_logs	部署日志末尾内容	否
rollback	将上一个可用发布版本设为当前运行版本	是（有破坏性）
github_deploy_runs	最近一次 Deploy to Plesk 运行的状态	否

每个工具都会声明 title、readOnlyHint、destructiveHint、idempotentHint 和 openWorldHint，并在可读文本旁返回结构化内容。

inspect_project

它会读取清单文件、锁定文件、运行时版本固定信息、框架配置、Dockerfile、CI、迁移文件和源代码。它会返回一个 Deployment facts 表，其中每条信息都标记为已验证（并附上来源文件）或未知，因此不会进行猜测。它还会列出各个应用的构建、启动和迁移命令，以及环境变量的名称，并区分构建时和运行时变量。

{ "project_dir": "/Users/me/code/acme" }

server_discovery_commands

它会返回一段只读命令，供你以 root 身份在服务器上运行后粘贴回来：Plesk 和操作系统、root 用户和域名用户下的 PM2、端口、nginx 指令、文档根目录、环境文件名称、数据库、crontab，以及 .env 和 .git 是否对外暴露。

{ "domain": "example.com", "app": "acme", "system_user": "acme_sys", "pm2_processes": ["acme-api"] }

generate_deploy_kit

它会生成以下文件：

• .github/workflows/deploy-plesk.yml
• deploy/plesk/：build-bundle.sh、<app>-deploy 发布管理器、deploy.conf.example、server-setup.sh、<app>-db-backup、PM2 或 systemd 配置、可选的 nginx 指令，以及 README.md

每个新文件都会显示为相对于其所依据的已审核模板的差异。对于它无法确定的值，会留作 FILL IN，并提供仍需由人工调整的内容列表。

{
  "project_dir": "/Users/me/code/acme",
  "app": "acme",
  "stack": "node",
  "process_manager": "pm2",
  "site_url": "https://example.com/",
  "public_health_url": "https://example.com/health",
  "base_dir": "/var/www/acme-app",
  "health_checks": [{ "url": "http://127.0.0.1:3001/health/ready", "contains": "\"status\":\"ready\"" }],
  "health_commit_url": "http://127.0.0.1:3001/health/ready",
  "pm2_apps": [{ "name": "acme-api", "dir": ".", "script": "dist/main.js" }],
  "database": "postgres",
  "migrate_cmd": "NODE_ENV=production node node_modules/typeorm/cli.js migration:run -d dist/data-source.js",
  "write": false
}

审阅并同意差异后，再次调用，并设置 "write": true。只有当你同意替换某个文件时，才添加 "overwrite": ["deploy/plesk/README.md"]。

validate_deploy_kit

它会运行以下检查：

• 对每个脚本运行 bash -n，若已安装 shellcheck，也会运行它
• 解析工作流的 YAML
• 检查工作流的安全设置：严格校验主机密钥、production 审批门禁、部署绝不取消、之后移除密钥、只读权限、可调用的 CI
• 检查发布管理器是否保留了所有安全检查
• 检查迁移之前是否运行了备份
• 扫描密钥，并报告文件和行号，绝不显示密钥值
• 针对你调整后的副本运行发布管理器自身的测试套件

{ "project_dir": "/Users/me/code/acme" }

server_discover

它会通过一个 SSH 会话运行 server_discovery_commands 列表。每条命令都会在超时限制下运行，并关闭标准输入；看起来像密钥的输出会被隐藏。添加 "sudo": true，即可通过 sudo -n 以 root 身份运行；这仅适用于配置了免密码 sudo 的情况。

{ "host_alias": "myserver", "domain": "example.com", "app": "acme" }

deploy_status

它会运行 /usr/local/bin/<app>-deploy --status，无需 sudo。

{ "host_alias": "myserver", "app": "acme" }

deploy_logs

它会运行 sudo -n <app>-deploy --log <lines>。日志仅限 root 访问，因此会通过部署账户唯一的 sudo 规则读取。

{ "host_alias": "myserver", "app": "acme", "lines": 100 }

rollback

它会运行 sudo -n <app>-deploy --rollback，并报告回滚前和回滚后当前生效的发布版本。迁移不会撤销；因此迁移必须始终只做新增（先扩展，再收缩）。

{ "host_alias": "myserver", "app": "acme", "confirm": "acme@myserver" }

github_deploy_runs

它会从 api.github.com 读取运行记录、其中的作业，以及正在等待审批的运行记录。对于私有仓库，请将 PLESK_DEPLOY_GITHUB_TOKEN 设置为具有 Actions: read 和 Metadata: read 权限的细粒度令牌。

{ "repo": "me/acme", "branch": "main", "limit": 5 }

资源和提示词

• plesk-deploy://workflow：8 个阶段以及绝不放宽的规则。
• plesk-deploy://references/<name>：discovery、hosting-models、github-actions、release-manager、environment-and-database、security-and-safety、verification-checklist、troubleshooting、rollback 和 worked-example。
• plesk-deploy://templates/<dir>/<file>：工具包所依据的 12 个模板，例如 plesk-deploy://templates/server/app-deploy。
• 提示词 setup-plesk-deployment，有两个可选参数：project_dir 和 host_alias。

配置

变量	含义
PLESK_DEPLOY_SSH_HOSTS	SSH 工具可连接的、以逗号分隔的 ~/.ssh/config 别名。未设置时，SSH 工具将关闭。
PLESK_DEPLOY_GITHUB_TOKEN	可选。用于在私有仓库中调用 github_deploy_runs 的只读细粒度令牌。
PLESK_DEPLOY_SSH_BIN	可选的 ssh 路径。默认使用 PATH 中的 ssh。

运行 npx -y plesk-deploy-mcp --help 查看此列表。

常见问题

它会从我的机器上部署吗？ 不会。部署会在 GitHub Actions 中运行，并且需要有人在 production 环境中批准。服务器在本地只会读取和渲染文件，并在临时文件夹中运行脚本。

别名应该使用哪个 SSH 账户？ 使用部署账户（<app>-deploy）。它唯一的 sudo 权限是运行发布管理器，因此 deploy_status、deploy_logs 和 rollback 都可以通过它运行。以 root 身份运行 server_discover 更有用，但它始终只运行只读命令。

它能读取我的 .env 吗？ 不能。在本地，真实的 .env 文件只会被报告为存在，绝不会打开。在服务器上，环境文件会由一条不输出其他任何内容的命令列出，格式为 NAME=<set> 或 NAME=<empty>，甚至不会输出多行值的续行。所有返回内容也都会经过脱敏处理。

为什么 generate_deploy_kit 被标记为有破坏性？ 它可以替换文件，但只会替换你在 overwrite 中列出的文件。默认情况下，它会进行试运行，不会写入任何内容。

我的服务器运行的是较旧版本的发布管理器。deploy_logs 还能用吗？ --log 是此工具包新增的功能。使用新版工具包重新运行 server-setup.sh，以重新安装发布管理器；或者自行以 root 身份读取日志。deploy_logs 会告诉你该怎么做。

如果我的服务器不是 Plesk，还能用吗？ 发布管理器和流水线可在任何支持 SSH 的 Linux 服务器上运行。Plesk 专用部分只有服务器发现命令和指导内容，涵盖文档根目录、nginx 指令、PHP-FPM 和系统用户。

Windows 呢？ 本地工具可在 Windows 上运行。validate_deploy_kit 的 shell 检查需要 bash；如果没有，它会将这些检查报告为已跳过。SSH 工具使用 Windows OpenSSH 客户端。

npx -y plesk-deploy-mcp 会运行哪个版本？ 最新版本，不过 npx 可能会复用缓存副本。若要固定版本，请使用 [email protected]。

贡献、安全与许可证

CONTRIBUTING.md 说明了如何参与代码开发。请私下报告漏洞（SECURITY.md）。采用 MIT 许可证（LICENSE）。