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
登录宝塔面板，进入「设置」->「常用设置」：
- 记下面板端口，例如
35335。 - 记下安全入口；例如
/a5cbfadd。它需要放进BT_PANEL_URL，但 API 请求会自动从站点根路径发起。 - 打开 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
