bt-panel-mcp-server

宝塔面板（BT Panel）MCP Server，让任意支持 MCP 协议的 AI 助手直接用自然语言查询服务器日志、管理网站、查看系统状态，不用再手动登录面板。

GitHub | npm

默认 只读模式，设置 BT_MODE=full 可开启全量管理工具。

这能做什么？

在任意支持 MCP 协议的 AI 工具（Cursor、Claude Desktop、Windsurf、Cline、Cherry Studio 等）的对话里直接说：

查询日志 & 监控

"帮我看看 example.com 最近的 Nginx 错误日志"

"查一下 shop.com 的 Laravel 日志有没有报错"

"服务器现在 CPU 和内存使用情况怎么样？"

一键建站部署（需要 BT_MODE=full）

"帮我生成一个小龙虾餐厅落地页，暗红色主题，部署到 claw.example.com，完成后给我访问地址"

"把刚才生成的活动报名 HTML 直接部署到服务器，用 IP 访问就行"

"把 example.com 首页的联系电话改成 138xxxxxxxx，直接更新到服务器"

网站 & 域名管理（需要 BT_MODE=full）

"帮我给 example.com 备份一下"

"给 example.com 绑定一个新域名 www.example.com"

"停用 test.example.com 这个测试站"

快速开始

第一步：开启宝塔面板 API

登录宝塔面板 → 左侧菜单「设置」→「常用设置」，参考下图找到以下三项：

1. 面板端口（红框①）：记下端口号，如 35335，面板地址为 http://服务器IP:端口

2. 安全入口（红框②）：若已设置，面板地址需要带上此路径，如 http://服务器IP:端口/a5cbfadd

3. API 接口（红框③）：打开开关 → 点击「API接口配置」→ 复制接口密钥，并将本机 IP 加入白名单（必须，否则请求会被拒绝）

第二步：配置 MCP

各 AI 工具的配置文件路径不同，找到对应的文件编辑即可：

推荐：npx 方式（无需手动下载，始终使用最新版）

{
  "mcpServers": {
    "bt-panel": {
      "command": "npx",
      "args": ["-y", "bt-panel-mcp-server"],
      "env": {
        "BT_PANEL_URL": "http://服务器IP:面板端口/安全入口",
        "BT_API_KEY": "你的API密钥",
        "BT_MODE": "readonly"
      }
    }
  }
}

本地方式（已克隆源码时使用）

{
  "mcpServers": {
    "bt-panel": {
      "command": "node",
      "args": ["本地路径/bt-panel-mcp-server/dist/index.js"],
      "env": {
        "BT_PANEL_URL": "http://服务器IP:面板端口/安全入口",
        "BT_API_KEY": "你的API密钥",
        "BT_MODE": "readonly"
      }
    }
  }
}

BT_PANEL_URL 怎么填？ 对照第一步截图中的信息拼接：

安全入口路径在「设置 → 常用设置 → 安全入口」中查看，没设置则不用填。

其余替换内容：

• 你的API密钥 → 第一步「API接口配置」页面中复制的接口密钥

• BT_MODE → readonly（只读，默认）或 full（含建站/写文件等管理操作）

第三步：重启 AI 工具

完全退出并重新打开你的 AI 工具，然后测试：

列出宝塔面板所有网站

环境变量

工具模式说明

readonly 模式（默认，安全）

只包含查询和读取工具，AI 无法对服务器做任何修改：

full 模式（BT_MODE=full）

在 readonly 所有工具基础上，额外开放：

工具详细说明

list_sites — 列出所有网站

get_nginx_logs — 查询 Nginx 日志（自动探测路径）

工具会自动在 /www/wwwlogs/ 目录下探测日志文件，无需手动填写路径；探测失败时会列出目录内容供参考。

get_app_logs — 查询应用层日志（自动探测框架路径）

工具会自动在网站根目录下按框架候选路径逐一探测，framework: auto 时尝试所有常见框架；探测失败时列出目录结构供参考。

各框架自动探测路径：

get_panel_logs — 查询面板操作日志

get_system_status — 查询服务器状态

无需参数，返回 CPU、内存、磁盘、网络实时数据。

read_file — 读取任意文件

get_nginx_config — 读取 Nginx 配置

manage_sites — 网站管理（full 模式）

manage_domains — 域名管理（full 模式）

manage_backups — 备份管理（full 模式）

对话使用示例

日志排查

查看 example.com 最近 500 行 Nginx 错误日志
example.com 最近有哪些 502 错误？
查看 shop.com 的 Laravel 日志有没有 Exception

系统状态

服务器现在 CPU 和内存使用率多少？
磁盘还有多少空间？

网站管理（full 模式）

帮我立即备份 example.com
给 example.com 添加域名 www.example.com
停用 example.com

配置查看

读取 example.com 的 Nginx 配置
查看 /www/wwwroot/example.com/.env 文件

🚀 场景案例：AI 生成网站 → 一键部署上线

需要 BT_MODE=full

这是 bt-mcp 最有趣的使用场景之一：让 AI 帮你生成网站内容，然后直接部署到服务器，全程不用手动登录面板。

案例一：小龙虾餐厅落地页（OpenClaw 风格）

你对 AI 说：

"帮我生成一个小龙虾餐厅的宣传落地页，暗红色主题，要有菜单、价格、联系方式，风格现代感强，然后部署到服务器，域名用 claw.myrestaurant.com"

AI 自动执行的步骤：

第一步：生成 HTML
  ↓ AI 生成完整的 index.html（暗红主题、菜单卡片、价格表、微信/电话联系）

第二步：调用 manage_sites（action=create）
  domain: claw.myrestaurant.com
  path:   /www/wwwroot/claw.myrestaurant.com
  → 宝塔自动创建目录 + Nginx 配置

第三步：调用 save_file
  path:    /www/wwwroot/claw.myrestaurant.com/index.html
  content: <刚生成的 HTML>
  → 文件写入服务器

第四步：返回访问地址
  ✅ 部署完成！访问地址：http://claw.myrestaurant.com
  ⚠️ 记得把域名 DNS 解析到你服务器的 IP

整个过程 30 秒内完成，你只需要去域名商把 DNS 指向服务器 IP 即可。

案例二：没有域名，用 IP 临时预览

你对 AI 说：

"帮我生成一个活动报名页，直接用服务器 IP 访问就行，不用配域名"

AI 会把域名字段填写为服务器 IP，宝塔建站后直接 http://服务器IP 访问。

案例三：已有网站，AI 更新内容

你对 AI 说：

"把 claw.myrestaurant.com 首页的营业时间改成 10:00-22:00，夏季特供区加一道'麻辣小龙虾拼盘 128元'"

AI 会：

1. read_file 读取现有 index.html

2. 修改对应文字

3. save_file 写回服务器

完全不用手动 SSH 或登录面板。

完整工作流示意

你的想法（自然语言）
       ↓
   AI 生成 HTML
       ↓
 bt-mcp 创建网站目录
       ↓
 bt-mcp 写入 index.html
       ↓
  域名解析（手动，一次性）
       ↓
   🌐 网站上线

提示：如果你的域名已经解析好，整个从「提需求」到「能访问」的过程可以压缩到 1 分钟以内。

常见问题

Q：提示 "Missing required environment variables"？

检查 BT_PANEL_URL 和 BT_API_KEY 是否正确填写，重启你的 AI 工具。

Q：提示请求失败或连接超时？

1. 确认宝塔面板地址和端口正确（默认 8888）

2. 确认已在宝塔 API 设置中添加了你的本机 IP 到白名单

3. 如果面板开启了 HTTPS 或安全入口，地址要包含完整路径（如 https://IP:端口/安全路径）

Q：读取日志提示文件不存在？

• Nginx 日志需要先在宝塔面板开启「访问日志」（网站设置 → 日志）

• 工具会自动探测并列出目录结构，根据提示补充 log_path 参数即可

Q：日志内容太多，AI 回复很慢？

使用 last_lines 参数限制读取行数，建议不超过 500 行。

Q：full 模式会有什么风险？

save_nginx_config 和 save_file 是写操作，配置错误可能导致网站无法访问。建议在熟悉 AI 行为后再开启 BT_MODE=full，平时保持默认 readonly。

本地开发

cd E:\tools\bt-mcp
npm install --ignore-scripts
npm run build
node dist/index.js   # 输出 "BT Panel MCP Server running (mode: readonly)"

监听文件变化自动重新编译：

npm run dev

技术栈

• 语言：TypeScript

• 运行时：Node.js >= 18

• MCP SDK：@modelcontextprotocol/sdk

License

MIT

联系作者

如有问题或建议，欢迎微信交流：