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