bt-ops-mcp-server

BT Ops MCP

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

简体中文 | English

概述

非官方独立项目 — 与宝塔面板官方无隶属或背书关系。

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）——在服务器运维场景下的一次典型实践：能力与可托付性作为同等优先的工程目标，贯穿设计与实现的全过程。相关理论和架构文档将另行发布。

快速开始

前置条件：Node.js ≥ 22，一台已开启 API 接口的宝塔面板服务器。

本服务器以 npm 包 bt-ops-mcp-server 发布， 无需预先安装，npx 会自动下载并运行。Cursor 与 Claude Desktop 使用相同的 MCP 配置：

{
  "mcpServers": {
    "bt-ops": {
      "command": "npx",
      "args": ["-y", "-p", "bt-ops-mcp-server", "bt-ops-mcp"]
    }
  }
}

Codex CLI 可直接注册：

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 个标记为破坏性。逐工具的名称、功能、分类、工具集与行为说明见 工具目录。

配置

首次启动时自动生成配置文件（~/.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。

面板 API 版本与维护说明

本项目基于宝塔面板 11.8.0 的 API 开发，全部接口均在该版本上经过真机验证。官方接口文档见 docs.bt.cn/api。

宝塔面板的 API 会随版本演进，且不提供对外的版本化契约。本项目不承诺随面板版本即时同步，也不承担长期维护义务：面板升级后，个别工具行为异常乃至失效属于可预期情形。如遇此类问题，可自行调整代码适配，或提交 issue 反馈，我们会在条件允许时评估并修复。

项目关系与商标说明： 本项目由开发者团队独立开发和维护，通过用户自行配置的面板 API 接口工作；“宝塔”“宝塔面板”“BT Panel”及相关名称归各自权利人所有。

给感兴趣的开发者

我们将开发过程中沉淀的设计与工程材料部分整理为公开文档，与安全声明一并汇总如下，统一托管于 GitHub 仓库（其中 docs/、devkit/ 与 tests/ 不随 npm 包分发）。如需更详细的开发或设计文档，欢迎联系我们。

文档	内容
SECURITY.md	安全边界与漏洞报告渠道
tools.md	自动生成的完整工具目录
CONSTITUTION.md	设计时宪法，供开发者参考
ARCHITECTURE.md	架构地图与工具扩展流程
field-notes.md	关于 AI 运维服务器的一些看法
devkit/	便于开发者扩展的工具包
tests/	77 个测试文件、508 个用例，与源码同构

许可证

Apache License 2.0。再分发时请一并保留 NOTICE。

由 Tangchangzhe 主导开发，Aniso Labs 团队协作。

BT Ops MCP · Aniso Labs