WHM Management Control Panel (MCP)

WHM 管理控制面板（MCP）

一个 Node.js 服务端应用，可连接 WHM（Web Host Manager）服务，以管理账户和服务器。本应用实现了 Model Context Protocol（MCP），让 Claude 等 AI 助手能够与 WHM API 交互。

功能

• 账户管理（创建、修改、暂停、终止）
• 服务器信息和统计数据
• 服务器更新和维护
• SSL 证书管理
• 备份管理
• 邮件账户管理
• 域名管理
• 安全功能
• 用于集成 AI 助手的 MCP 协议实现

快速开始

你需要 Node.js 18 或更高版本，以及 WHM API 令牌。

1. 为服务创建一个文件夹，并在其中创建 .env 文件：

   WHM_SERVER=your-server-domain.com
   WHM_PORT=2087
   WHM_USERNAME=root
   WHM_API_TOKEN=your-whm-api-token
   # Only if WHM is reached by IP or uses a self-signed certificate:
   # WHM_INSECURE_TLS=true
   
   PORT=3000
   # Required: the server refuses to start without it. Generate one with: openssl rand -hex 32
   API_KEY=your-long-random-api-key
   

2. 在该文件夹中启动 MCP 服务：

   npx whm-mcp-server
   

   或者克隆此代码仓库，运行 npm install，然后运行 npm run mcp。

MCP 端点为 http://localhost:3000/sse（端口由 PORT 指定；如果未设置 PORT，则使用 4444）。

MCP 客户端配置

每个请求都必须发送 API 密钥，可通过 Authorization: Bearer <API_KEY> 或 X-API-Key: <API_KEY> 发送。不带密钥的请求会收到 401 Unauthorized。

对于支持使用标头连接远程服务的客户端（例如 Cursor），请将以下内容添加到 mcp.json：

{
  "mcpServers": {
    "whm": {
      "url": "https://your-mcp-host:3000/sse",
      "headers": { "Authorization": "Bearer your-long-random-api-key" }
    }
  }
}

对于只能运行本地命令的客户端（例如 Claude Desktop），请使用 mcp-remote 桥接程序：

{
  "mcpServers": {
    "whm": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://your-mcp-host:3000/sse", "--header", "Authorization: Bearer your-long-random-api-key"]
    }
  }
}

请在 HTTPS 和防火墙后运行此服务：任何拥有密钥的人都可以管理 WHM 服务。

REST API（可选）

npm start 会运行一个独立的 REST API（/api/...，见下文），它同样需要 API 密钥，并通过 X-API-Key 标头发送。

MCP 实现详情

此服务使用 HTTP Server-Sent Events（SSE）作为传输机制，实现了 Model Context Protocol。所有消息均遵循标准 JSON-RPC 2.0 格式，并包含：

• 用于建立持久连接的 /sse 端点
• 用于接收并响应客户端请求的 /messages 端点
• 主动发送 connection/ready 和 tools/ready 通知
• 使用适当错误代码的标准化错误处理

MCP 架构通过定义明确且具有特定参数架构的工具，让 AI 助手能够安全地使用 WHM 功能，在大模型与服务器管理功能之间搭建安全桥梁。

可用的 MCP 工具

MCP 服务通过工具提供以下 WHM 功能：

账户管理

• whm_list_accounts - 列出所有 WHM 账户
• whm_create_account - 创建新的 cPanel 账户
• whm_account_summary - 获取账户详情
• whm_suspend_account - 暂停 cPanel 账户
• whm_unsuspend_account - 恢复 cPanel 账户
• whm_terminate_account - 永久删除账户

服务器管理

• whm_server_status - 获取服务器状态和系统统计数据
• whm_server_load - 获取服务器负载统计数据
• whm_service_status - 获取服务器服务的状态
• whm_restart_service - 重启指定的服务器服务
• whm_check_updates - 检查可用更新
• whm_start_update - 启动服务器更新流程

域名管理

• whm_list_domains - 列出账户的域名
• whm_add_domain - 为账户添加域名
• whm_delete_domain - 从账户中移除域名

API 文档

API 端点按资源类型组织：

• /api/accounts - 账户管理操作
• /api/server - 服务器信息和操作
• /api/domains - 域名管理
• /api/ssl - SSL 证书管理
• /api/backups - 备份管理操作
• /api/email - 邮件账户管理

启动服务后，访问 /docs 端点查看详细 API 文档。

安全

此应用需要 WHM API 凭据。切勿分享 .env 文件或公开 API 令牌。

安全最佳实践

使用此 MCP 服务管理 WHM 时，请遵循以下安全建议：

1. 保护 API 令牌：妥善保管 WHM API 令牌，并定期轮换。尽可能创建仅具备所需权限的 WHM API 令牌，而不要使用完整的 root 访问权限。
2. 使用 TLS/SSL：在生产环境中始终通过 HTTPS 部署此服务。
3. 防火墙规则：尽可能按 IP 地址限制对 MCP 服务的访问。
4. 定期更新：为 WHM 服务安装最新的安全补丁。
5. 监控：实施监控，以检测异常活动或未授权的访问尝试。
6. 备份策略：定期备份所有服务配置和数据。

网站遭入侵与 Root 权限遭入侵

请注意网站遭入侵与 root 权限遭入侵的区别：

• 网站遭入侵只会影响特定网站，而 root 权限遭入侵则会暴露整个服务。
• 发生任何入侵事件时，请从备份中恢复，并找出攻击入口。
• 有关 WHM 安全详情，请参阅 cPanel 安全最佳实践。

测试

你可以使用随附的示例客户端测试 MCP 服务：

npm run example

这将运行一个简单的测试客户端，连接到 MCP 服务、请求可用工具并执行示例命令。

许可证

ISC

---

关于 Host Hobbit

由 Host Hobbit Ltd 构建并维护：为英国企业提供托管式 WordPress 托管、WHM/cPanel 和 VPS 管理、安全加固及 AI 自动化服务。

需要帮助部署此服务，或希望为你的企业构建类似方案？联系我们。