bt-panel-mcp-server

让支持 MCP 的 AI 助手安全地操作宝塔面板（BT Panel）。它既提供适合日常运维的高层工具，也内置当前官方 API 文档中的完整操作目录：先检索接口定义，再以受控方式调用。

GitHub | npm | 宝塔官方 API 文档

能力概览

默认是 readonly，不会暴露写入或管理操作。只有明确设置 BT_MODE=full 才会启用完整管理能力。

官方 API 覆盖范围

内置目录来自宝塔官方 API 文档当前验证基线（面板 v11.7.0，文档提交 1f8efe62fa9757d71a7259b063bd63e3775e2e3c），共 369 个可执行操作。它不是把数百个工具同时塞入客户端，而是提供下面的稳定流程：

search_bt_api  ->  get_bt_api_operation  ->  call_bt_api
查找能力           核对参数和路由              在 full 模式执行

目录覆盖的是官方文档中的操作定义。目标面板是否能实际执行，仍取决于面板版本、插件是否安装、API 白名单、账号权限及参数有效性。

工具清单

readonly 模式

full 模式新增工具

BT_API_KEY、request_time、request_token 与目录规定的 action 不接受 MCP 调用方传入，均由服务端生成或注入。

快速开始

1. 开启宝塔 API

登录宝塔面板，进入「设置」->「常用设置」：

1. 记下面板端口，例如 35335。
2. 记下安全入口；例如 /a5cbfadd。它需要放进 BT_PANEL_URL，但 API 请求会自动从站点根路径发起。
3. 打开 API 接口，复制接口密钥，并将 MCP 运行主机 IP 加入 API 白名单。

2. 配置 MCP 客户端

推荐通过 npx 运行：

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

本地源码运行时，把 args 改为本项目 dist/index.js 的绝对路径。配置文件位置因 Cursor、Claude Desktop、Windsurf、Cherry Studio、Cline 等客户端而不同，请使用各客户端的 MCP 设置入口。

3. 先做只读连通性检查

重启 MCP 客户端后，先让 AI 执行：

列出宝塔面板的所有网站，并告诉我当前服务器 CPU、内存和磁盘使用情况。

成功后再按需把 BT_MODE 改为 full 并重启客户端。不要在不理解影响范围时直接要求 AI 删除、升级或重启服务。

环境变量

安全入口、API 密钥、密码、Token、证书私钥和数据库凭据都不应写入自然语言提示词、URL、浏览器代码或 Git 仓库。

使用官方 API 目录

查询一个能力

例如让 AI 查找 Docker 容器、数据库或证书操作：

搜索宝塔官方 API 中与 Docker 容器列表有关的操作，列出可用 ID 和必填参数。

也可以直接调用 search_bt_api：

{ "query": "容器列表", "module": "docker", "include_parameters": false }

获取准确参数

对要执行的操作先调用 get_bt_api_operation：

{ "operation": "database/GetDatabasesList" }

返回结果会包含请求方法、路径、固定 action、必填参数、类型和官方说明。不要根据猜测拼参数。

执行操作

确认目的和参数后，在 BT_MODE=full 下调用 call_bt_api：

{
  "operation": "database/GetDatabasesList",
  "params": {
    "p": 1,
    "limit": 20,
    "sid": 0
  }
}

对于带密码、私钥、DNS API Key 或容器配置的操作，params 仍可能包含敏感数据；仅在用户已明确授权向其自己的宝塔面板发送这些值时执行。

常见工作流

故障排查

1. 列出站点并确认目标名称
2. 读取最近 200 行 Nginx error 日志
3. 读取应用日志，比较同一时间段的异常
4. 查询系统负载、内存、磁盘和网络
5. 只在原因明确后修改配置；修改前先读取原文件并保留回滚内容

可直接对 AI 说：

排查 example.com 最近的 502：先看 Nginx 错误日志、再看应用日志和系统负载；只报告证据，不修改任何配置。

建站和内容发布

1. 用 manage_sites 创建站点和目录
2. 用 list_domains / manage_domains 核对域名绑定
3. 用 save_file 写入 index.html 或应用配置
4. 用 get_nginx_config 复核虚拟主机配置
5. 在公网或目标网络访问站点，确认 HTTP 状态、证书和内容

数据库、证书、Docker 或计划任务

1. search_bt_api 找到准确的官方操作
2. get_bt_api_operation 读取参数、前置条件与影响范围
3. full 模式下 call_bt_api 执行
4. 再用对应查询操作验证最终状态、日志或任务结果

涉及删除、覆盖、重启、升级、清理 Binlog、证书替换、容器删除或数据库用户权限变更时，应先说明目标对象、影响范围和回滚方式，再执行。

边界与安全模型

• readonly 不提供写入和官方 API 调用，但 read_file 仍能读取指定文件；不要读取无关的 .env、私钥或凭据文件。
• full 是权限开关，不是自动授权。执行破坏性操作前应取得针对具体目标的明确许可。
• call_bt_api 只允许调用内置官方目录中的操作，不接受任意 URL、任意 HTTP 方法或用户自定义 action。
• API 目录来自文档，不是目标主机的能力探测。某些 Docker、Java、反向代理、SSL 或商业插件接口在未安装时会失败。
• HTTPS 默认验证服务端证书。自签名证书需要显式设置 BT_ALLOW_INSECURE_TLS=true，此时应确保访问网络可信。
• API 接口可能随宝塔面板版本变更；每次面板大版本升级后，应先在测试环境验证关键调用。

常见问题

提示 Missing required environment variables

检查 MCP 进程环境中是否同时有 BT_PANEL_URL 和 BT_API_KEY，修改后完全重启客户端。

请求超时、403 或 API 白名单错误

确认面板地址/端口正确，MCP 主机 IP 已加入 API 白名单，且防火墙、安全组允许访问面板端口。安全入口需要写入 BT_PANEL_URL。

HTTPS 连接报证书错误

优先为面板配置可信证书。只有在确认内网链路和目标身份可信时才设置 BT_ALLOW_INSECURE_TLS=true。

官方操作执行失败

先用 get_bt_api_operation 重查参数，再确认面板版本、对应插件、账户权限和 API 白名单。文档目录覆盖不保证旧版本面板或未安装插件支持该操作。

full 模式有什么风险

它可以修改站点、配置、文件、数据库、证书、容器和系统服务。对生产环境应保持备份、先读取现状、执行后独立验证，并保留回滚内容。

本地开发与目录更新

npm ci
npm run build
node dist/index.js

更新官方目录时，先获取 cnb.cool/btpanel/docs，再运行：

$env:BT_OFFICIAL_DOCS_DIR = 'D:\src\btpanel-docs'
$env:BT_OFFICIAL_DOCS_REVISION = (git -C $env:BT_OFFICIAL_DOCS_DIR rev-parse HEAD)
npm run generate:api-catalog
npm run build

生成后应检查操作数量、抽查 GET/POST 路由和必填参数，再在目标面板或测试面板验证重点插件接口。

技术栈

• TypeScript
• Node.js >= 20
• @modelcontextprotocol/sdk
• 宝塔官方 API 文档目录生成器

License

MIT