BT Ops MCP

面向宝塔面板的受控运维网关。服务于开发者与 AI 协同运维服务器，在用户授权范围内提供 观察、分析、执行与核实能力，并保障用户的最终控制权。

简体中文 | English

非官方项目 — 本项目由开发者团队独立开发，与宝塔面板官方无隶属或背书关系，通过用户自行配置的面板 API 接口工作。"宝塔""宝塔面板""BT Panel" 及相关名称归各自权利人所有。

概述

BT Ops MCP 是一个运行在 AI 客户端与宝塔面板之间的 MCP（Model Context Protocol）服务器。AI 可以通过本项目帮助开发者或团队运维服务器，完成日常任务并解决问题。

现代服务器运维同时依赖指标、日志、追踪、配置、依赖拓扑和公网可用性等多源信号。信息分散、上下文切换频繁、知识跨度大和经验依赖强，是开发者与团队共同面对的成本。这类工作与 AI 的能力形态天然契合：它可以承担大量重复的信息收集、资料检索与汇总诊断，并执行标准化操作，让人把注意力留给高风险判断与例外处置。随着能力普及和成本下降，这种协作正在从偶发辅助转向可持续的运维基础能力。

服务器运维相较于其他场景最大的特殊之处，在于误操作的后果风险较高——把 Shell 或 API 简单封装后直接交给 AI，可能造成不可预测且难以撤销的后果。本项目提供了 50+ 覆盖服务器运维核心场景的工具，设计了一系列不依赖于 AI 表现的安全与信任机制和 AI 原生功能，在提升 AI 解决问题的能力、效率和准确率的同时，将 AI 操作服务器的风险约束在使用者认可的范围之内，并保障使用者的最终控制权。

本项目同时是 Aniso Labs 提出的 AI 垂直领域理论——能力与可托付性工程（Capable and Entrustable Engineering）——在服务器运维场景下的一次典型实践：能力与可托付性作为同等优先的工程目标，贯穿设计与实现的全过程。相关理论和架构文档将另行发布。

Related MCP server: pterodactyl-mcp

快速开始

前置条件：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。

核心优势

• 全面且安全的工具集 — 52 个工具覆盖服务器 9 大核心运维场景，提升 AI 运维能力上限。所有工具经过层层真机验证，明确标注只读性、破坏性与幂等性；剔除语义不可信或含隐式写操作的接口，不为功能盲目增加工具类型，确保 AI 调用工具的稳定与确定性

• 多实例隔离运维 — 支持同时接入并运维多台宝塔面板服务器。每台实例持有独立的 API 密钥、权限策略、工具白名单与数据目录，通过机制隔离使 AI 跨服务器操作互不干扰

• AI 原生设计 — 采用 MCP 协议的 Instructions 与 Resources 按需加载机制，搭配工具集最小暴露、严密的结果状态机、结构化报错、上下文截断与翻页等机制，帮助 AI 快速定位并高效完成任务，同时大幅降低基础上下文 Token 开销

• 保守失败语义与人工在环 — 写操作结果无法确认时自动保留未知状态并引导先行核实；远端内容标记为不可信数据，高风险写操作要求人工确认；通过机制与提示词工程共同降低 AI 不可预测的操作风险

• 开箱即用的 GUI 管理 — 提供本地可视化设置页，无需手动编辑 JSON 配置文件；支持快速添加服务器并配置，一键切换权限档位、预设工具集或自定义逐工具开关

• 路径遍历防护 — 自由路径参数强制绝对路径校验，防范 .. 等遍历攻击；支持读写差异化隔离策略（默认宽读窄写，可自定义），精确收敛 AI 的文件读取与操作边界

• 网络防护 — 为公网探测类功能构建 SSRF 防御，限定协议、端口与目标地址并逐跳复核 DNS 与重定向；本地设置页以 Host 与 Origin 校验抵御 DNS rebinding 和 CSRF

• 敏感凭据自动脱敏 — 自动识别并掩码结构化响应中的密钥、密码等常见敏感字段，防止敏感凭据向 AI 泄露；默认开启，支持自定义开关

• 操作追溯与备份 — 每次写操作在发起前自动记录完整参数、意图与执行状态，配置覆盖类写操作可在执行前保存旧状态，为人工审计、状态核实与恢复提供依据；同时内置操作记录读取工具，为 AI 辅助排查提供入口

能力范围

52 个工具（49 个业务工具，3 个内置工具），覆盖 9 个服务器运维能力域：

按行为划分：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 执行、进程管理、面板自身设置修改、回收站恢复与清空等功能。 完整的安全边界声明与漏洞报告渠道见 SECURITY.md。

文档

许可证

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

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

BT Ops MCP · Aniso Labs