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 工具的配置文件路径不同，找到对应的文件编辑即可：

AI 工具	系统	配置文件路径
Cursor	Windows	%USERPROFILE%\.cursor\mcp.json
Cursor	macOS / Linux	~/.cursor/mcp.json
Claude Desktop	Windows	%APPDATA%\Claude\claude_desktop_config.json
Claude Desktop	macOS	~/Library/Application Support/Claude/claude_desktop_config.json
Windsurf	Windows	%USERPROFILE%\.codeium\windsurf\mcp_config.json
Windsurf	macOS	~/.codeium/windsurf/mcp_config.json
Cherry Studio	—	设置 → MCP 服务器 → 添加
Cline / Roo Code	—	插件设置 → MCP Servers
其他工具	—	参考对应工具文档中"MCP Server"配置说明

推荐：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 怎么填？ 对照第一步截图中的信息拼接：

情况	填写示例
默认端口 8888，无安全入口	http://123.456.789.0:8888
自定义端口，无安全入口	http://123.456.789.0:35335
自定义端口 + 安全入口	http://123.456.789.0:35335/a5cbfadd
开启了面板 HTTPS	https://123.456.789.0:35335/a5cbfadd

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

其余替换内容：

• 你的API密钥 → 第一步「API接口配置」页面中复制的接口密钥
• BT_MODE → readonly（只读，默认）或 full（含建站/写文件等管理操作）

第三步：重启 AI 工具

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

列出宝塔面板所有网站

---

环境变量

变量名	必填	默认值	说明
BT_PANEL_URL	✅	—	宝塔面板地址，如 http://192.168.1.100:8888，支持 HTTPS 和安全入口路径
BT_API_KEY	✅	—	宝塔面板 API 接口密钥
BT_MODE	否	readonly	工具集模式：readonly 只读安全模式 / full 全量管理模式（含写操作）

---

工具模式说明

readonly 模式（默认，安全）

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

工具	说明
list_sites	列出所有网站
get_nginx_logs	读取 Nginx 访问/错误日志（自动探测路径）
get_app_logs	读取应用层业务日志（自动探测框架路径）
get_panel_logs	读取面板操作日志
get_system_status	查询 CPU/内存/磁盘/网络实时状态
read_file	读取服务器任意文件（只读）
get_nginx_config	读取网站 Nginx 配置文件（只读）
list_domains	查询网站绑定的域名列表
list_backups	查询网站备份列表

full 模式（BT_MODE=full）

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

工具	说明
manage_sites	创建/删除/启用/停用网站，修改备注、到期时间
manage_domains	绑定/解绑域名
manage_backups	立即备份/删除备份
save_nginx_config	修改保存 Nginx 配置（⚠️ 谨慎，即时生效）
save_file	写入服务器文件（⚠️ 谨慎）

---

工具详细说明

list_sites — 列出所有网站

参数	类型	必填	说明
search	string	否	按网站名称模糊搜索

---

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

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

参数	类型	必填	默认值	说明
site_name	string	✅	—	网站域名，如 example.com
log_type	string	否	access	access（访问日志）或 error（错误日志）
last_lines	number	否	200	读取最后 N 行（最大 2000）
log_path	string	否	—	手动指定路径（自动探测失败时使用）

---

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

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

参数	类型	必填	默认值	说明
site_name	string	二选一	—	网站名称，自动推断路径
log_path	string	二选一	—	手动指定日志文件绝对路径
framework	string	否	auto	auto（自动）/ laravel / thinkphp / java / nodejs
last_lines	number	否	200	读取最后 N 行（最大 2000）

各框架自动探测路径：

框架	候选路径
Laravel	storage/logs/laravel.log、storage/logs/app.log
ThinkPHP	runtime/log、runtime/logs/app.log
Java	logs/app.log、logs/error.log、app.log
Node.js	logs/app.log、logs/error.log、out.log

---

get_panel_logs — 查询面板操作日志

参数	类型	必填	默认值	说明
limit	number	否	30	返回最近 N 条记录（最大 100）

---

get_system_status — 查询服务器状态

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

---

read_file — 读取任意文件

参数	类型	必填	说明
path	string	✅	文件绝对路径
last_lines	number	否	只读最后 N 行，大文件必填

---

get_nginx_config — 读取 Nginx 配置

参数	类型	必填	说明
site_name	string	✅	网站名称（域名）

---

manage_sites — 网站管理（full 模式）

参数	类型	必填	说明
action	string	✅	start / stop / delete / create / set_note / set_expiry / get_php_versions / get_site_info
site_name	string	视情况	网站名称
path	string	create 必填	网站根目录
php_version	string	否	PHP 版本，如 74、80、81
note	string	否	备注
edate	string	set_expiry 必填	到期日期（YYYY-MM-DD 或 0000-00-00 永久）
delete_ftp / delete_db / delete_path	boolean	否	delete 时是否同时删除关联资源

---

manage_domains — 域名管理（full 模式）

参数	类型	必填	说明
action	string	✅	list / add / delete
site_name	string	✅	网站名称
domain	string	add/delete 必填	要操作的域名
port	number	否	端口，默认 80

---

manage_backups — 备份管理（full 模式）

参数	类型	必填	说明
action	string	✅	list / create / delete
site_name	string	✅	网站名称
backup_id	number	delete 必填	备份 ID（从 list 获取）

---

对话使用示例

日志排查

查看 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

---

联系作者

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