BT Ops MCP

npm version npm monthly downloads Node.js 22 or later Apache 2.0 license Model Context Protocol

面向宝塔面板的受控运维网关，深度优化的 AI 原生设计，轻量接入、便捷启用。

简体中文 | English

BT Ops MCP
## 概述 > **非官方独立项目** — 与宝塔面板官方无隶属或背书关系。 BT Ops MCP 是一个运行在 AI 客户端与宝塔面板之间的 MCP（Model Context Protocol）服务器。AI 可以通过本项目帮助开发者或团队运维服务器，完成日常任务并解决问题。 现代服务器运维同时依赖指标、日志、追踪、配置、依赖拓扑和公网可用性等多源信号。信息分散、上下文切换频繁、知识跨度大和经验依赖强，是开发者与团队共同面对的成本。这类工作与 AI 的能力形态天然契合：它可以承担大量重复的信息收集、资料检索与汇总诊断，并执行标准化操作，让人把注意力留给高风险判断与例外处置。随着能力普及和成本下降，这种协作正在从偶发辅助转向可持续的运维基础能力。 服务器运维相较于其他场景最大的特殊之处，在于误操作的后果风险较高——把 Shell 或 API 简单封装后直接交给 AI，可能造成不可预测且难以撤销的后果。本项目基于宝塔面板 API（11.8.0）开发了 48 个覆盖服务器运维核心场景的工具，并通过一系列不依赖于 AI 表现的安全与信任机制及 AI 原生设计，在提升 AI 解决问题的能力、效率和准确率的同时，将 AI 操作服务器的风险约束在使用者认可的范围之内，并保障使用者的最终控制权。除此之外，本项目对 MCP 的安装、启动与配置流程进行了大量优化，显著降低了接入与日常使用门槛。 本项目同时是 Aniso Labs 提出的 AI 垂直领域理论——**能力与可托付性工程（Capable and Entrustable Engineering）**——在服务器运维场景下的一次典型实践：能力与可托付性作为同等优先的工程目标，贯穿设计与实现的全过程。本项目也是 EntrustOps（可托付运维）方案在宝塔面板场景下的开源实践原型，用于验证面向服务器运维的低幻觉 Harness 架构。相关理论和架构文档将另行发布。 ## 快速开始 前置条件：Node.js ≥ 22，一台已开启 API 接口的宝塔面板服务器。 本服务器以 npm 包 [`bt-ops-mcp-server`](https://www.npmjs.com/package/bt-ops-mcp-server) 发布， 无需预先安装，`npx` 会自动下载并运行。Cursor 与 Claude Desktop 使用相同的 MCP 配置： ```json { "mcpServers": { "bt-ops": { "command": "npx", "args": ["-y", "-p", "bt-ops-mcp-server", "bt-ops-mcp"] } } } ``` Codex CLI 可直接注册： ```bash codex mcp add bt-ops -- npx -y -p bt-ops-mcp-server bt-ops-mcp ``` 其他支持 MCP（stdio 传输）的客户端同理：启动命令均为 `npx -y -p bt-ops-mcp-server bt-ops-mcp`，按各自客户端的方式注册即可。 重启客户端后，打开本机设置页（可手动打开，或让 AI 辅助打开，详见下文「配置」一节）， 填入面板地址与 API 密钥并保存；再次重启客户端即可使用。 也可从源码运行：克隆仓库后执行 `npm install && npm run build`，并将 MCP 配置中的 `command` 改为 `node`、`args` 指向本地的 `dist/index.js`。 ## 核心优势 - **全面且安全的工具集** — 48 个工具覆盖服务器 8 个核心运维能力域，另有 4 个工具用于管理 MCP 自身，提升 AI 运维能力上限。所有工具经过层层真机验证，明确标注只读性、破坏性与幂等性；剔除语义不可信或含隐式写操作的接口，不为功能盲目增加工具类型，确保 AI 调用工具的稳定与确定性 - **多实例隔离运维** — 支持同时接入并运维多台宝塔面板服务器。每台实例持有独立的权限策略与工具白名单，通过机制隔离使 AI 跨服务器操作互不干扰 - **AI 原生设计** — 采用 MCP 协议的 Instructions 与 Resources 按需加载机制，搭配工具集最小暴露、严密结果状态机、结构化报错、上下文截断与翻页等机制，帮助 AI 高效处理问题并完成任务，同时大幅降低基础上下文 Token 开销 - **轻量接入与配置** — 使用 `npx` 即可直接启动，无需预先安装或单独部署常驻服务；通过本地可视化设置页完成面板接入、权限档位、工具白名单、路径围栏与写前备份配置 - **路径遍历防护** — 自由路径参数强制绝对路径校验，防范 `..` 等遍历攻击；支持读写差异化隔离策略（默认宽读窄写，可自定义），精确收敛 AI 的文件读取与操作边界 - **网络防护** — 为公网探测类功能构建 SSRF 防御，限定协议、端口与目标地址并逐跳复核 DNS 与重定向；本地设置页以 Host 与 Origin 校验抵御 DNS rebinding 和 CSRF - **输出处理** — 可自动识别并掩码结构化响应中的密钥、密码等常见敏感字段，防止凭据泄露，支持开关；远端正文恒定标注为非指令的信息数据，减少 AI 执行其中包含的未知命令与链接的风险 - **操作追溯与备份** — 每次写操作在发起前自动记录完整参数、意图与执行状态，配置覆盖类写操作可在执行前保存旧状态，为人工审计、状态核实与恢复提供依据；同时内置操作记录读取工具，为 AI 辅助排查提供入口 ## 能力范围 共 52 个工具：48 个覆盖 8 个服务器运维能力域，另有 4 个 `meta` 工具用于管理 MCP 自身（其中 3 个为内置工具，随运行模式固定提供，不可关闭）。 | 域 | 覆盖 | | ---------- | ----------------------------------------------------------------- | | `system` | 系统资源概览、面板操作日志、Nginx / MySQL 启动与重启、Nginx 重载、SSH 基线检查、WebHook 查询与管理 | | `site` | 站点列表与聚合详情、建站、站点文件备份、Nginx 主配置与伪静态读写、SSL 证书与 ACME 订单查询、续签 | | `database` | MySQL 库表查询、备份、慢查询与错误日志、运行状态、删除 | | `files` | 目录浏览、文本文件读写、创建、移动、删除、权限与体积查询、回收站列表 | | `cron` | 计划任务列表、详情与执行日志（只读） | | `docker` | 本地镜像及使用它们的容器（只读） | | `env` | 运行组件的安装与版本状态（只读） | | `network` | 从网关主机发起的受限公网 HTTP/HTTPS 探测 | | `meta` | MCP 自身管理：设置页入口、运行时配置快照、本机写记录与备份读取、受限模式诊断 | 按行为划分：35 个只读，17 个写入，其中 12 个标记为破坏性。逐工具的名称、功能、分类、工具集与行为说明见 [工具目录](https://github.com/tangchangzhe/bt-ops-mcp-server/blob/main/docs/tools.md)。 ## 配置 首次启动时自动生成配置文件（`~/.config/bt-ops-mcp/config.json`）。推荐通过可视化设置页进行配置，不建议手动编辑 JSON 文件或让 AI 修改——本 MCP 未向 AI 侧提供任何可以改写配置的工具。 写操作记录、写前备份等运行数据默认保存在 `~/.config/bt-ops-mcp/bt-ops-mcp-data/`， 数据目录可在设置页自定义。 打开设置页有两种方式： - **让 AI 打开（推荐）** — 在任意已接入本 MCP 的客户端中，让 AI 调用 `open_settings` 工具， 它会在本机启动设置页并返回访问地址 - **手动打开** — 在任意目录运行 `npx -y -p bt-ops-mcp-server bt-ops-mcp-settings`；全局安装后可直接运行 `bt-ops-mcp-settings`。从源码运行也可在构建后执行 `node dist/settings/launcher.js`， Windows 还可双击 `settings/open-settings.cmd` 设置页支持：添加 / 管理多台服务器、选择权限档与工具集预设、自定义逐工具开关、调整路径围栏读写范围、开关脱敏与写前备份。保存后重启 MCP 客户端生效。 填写面板地址时，建议为面板开通 HTTPS 并填写最终的 HTTPS 地址：HTTP 明文传输或中途重定向可能被恶意利用，造成密钥与数据泄露。 ## 能力边界 不提供通用 Shell、任意 SQL 执行、进程管理、面板自身设置修改、回收站恢复与清空等功能。 其他暂不提供的常用工具（如递归路径扫描），大多是因为官方 API 存在隐式副作用、相关能力违反安全原则，或会对 AI 解决问题产生负面作用。 完整的安全边界声明与漏洞报告渠道见 [SECURITY.md](https://github.com/tangchangzhe/bt-ops-mcp-server/blob/main/SECURITY.md)。 ## 面板 API 版本与维护说明 本项目基于宝塔面板 **11.8.0** 的 API 开发，全部接口均在该版本上经过真机验证。官方接口文档见 [docs.bt.cn/api](https://docs.bt.cn/api/)。 宝塔面板的 API 会随版本演进，且不提供对外的版本化契约。本项目不承诺随面板版本即时同步，也不承担长期维护义务：面板升级后，个别工具行为异常乃至失效属于可预期情形。如遇此类问题，可自行调整代码适配，或[提交 issue](https://github.com/tangchangzhe/bt-ops-mcp-server/issues) 反馈，我们会在条件允许时评估并修复。 **项目关系与商标说明：** 本项目由开发者团队独立开发和维护，通过用户自行配置的面板 API 接口工作；“宝塔”“宝塔面板”“BT Panel”及相关名称归各自权利人所有。 ## 给感兴趣的开发者 我们将开发过程中沉淀的设计与工程材料部分整理为公开文档，与安全声明一并汇总如下，统一托管于 GitHub 仓库（其中 `docs/`、`devkit/` 与 `tests/` 不随 npm 包分发）。如需更详细的开发或设计文档，欢迎联系我们。 | 文档 | 内容 | | --------------------------------------------------------------------------------------------------- | ---------------------- | | [SECURITY.md](https://github.com/tangchangzhe/bt-ops-mcp-server/blob/main/SECURITY.md) | 安全边界与漏洞报告渠道 | | [tools.md](https://github.com/tangchangzhe/bt-ops-mcp-server/blob/main/docs/tools.md) | 自动生成的完整工具目录 | | [CONSTITUTION.md](https://github.com/tangchangzhe/bt-ops-mcp-server/blob/main/docs/CONSTITUTION.md) | 设计时宪法，供开发者参考 | | [ARCHITECTURE.md](https://github.com/tangchangzhe/bt-ops-mcp-server/blob/main/docs/ARCHITECTURE.md) | 架构地图与工具扩展流程 | | [field-notes.md](https://github.com/tangchangzhe/bt-ops-mcp-server/blob/main/docs/field-notes.md) | 关于 AI 运维服务器的一些看法 | | [devkit/](https://github.com/tangchangzhe/bt-ops-mcp-server/tree/main/devkit) | 便于开发者扩展的工具包 | | [tests/](https://github.com/tangchangzhe/bt-ops-mcp-server/tree/main/tests) | 77 个测试文件、508 个用例，与源码同构 | ## 许可证 [Apache License 2.0](https://github.com/tangchangzhe/bt-ops-mcp-server/blob/main/LICENSE)。再分发时请一并保留 [NOTICE](https://github.com/tangchangzhe/bt-ops-mcp-server/blob/main/NOTICE)。 由 Tangchangzhe 主导开发，Aniso Labs 团队协作。 --- *BT Ops MCP · Aniso Labs*