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）——在服务器运维场景下的一次典型实践：能力与可托付性作为同等优先的工程目标，贯穿设计与实现的全过程。本项目也是 EntrustOps（可托付运维）方案在宝塔面板场景下的开源实践原型，用于验证面向服务器运维的低幻觉 Harness 架构。相关理论和架构文档将另行发布。

快速开始

前置条件：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 个为内置工具，随运行模式固定提供，不可关闭）。

Shortened. The full README is on GitHub.