Skip to main content
Glama
tangchangzhe

bt-ops-mcp-server

by tangchangzhe
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Local

概述

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

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 架构。相关理论和架构文档将另行发布。

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。

核心优势

  • 全面且安全的工具集 — 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

Available Tools

2 tools
get_settings_statusA
Read-onlyIdempotent

内置工具，无法关闭；受限模式下返回未进入业务模式的原因、配置路径和下一步。

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

TDQS

A4.4/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, establishing a safe read-only operation. The description adds context by noting the tool is built-in and cannot be turned off, and specifies the exact information it returns (reasons, configuration path, next steps). This goes beyond basic metadata without contradicting annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, compact sentence that front-loads the key context (built-in, cannot be disabled) followed by the functional output. Every word adds value—no fluff or repetition—making it highly efficient for an AI agent to parse.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a zero-parameter, read-only status tool with no output schema, the description provides a complete picture: what it does (returns status info), when it applies (restricted mode), and what content it returns (reasons, path, next steps). It doesn't mention return format, but that's not required given the simplicity and the tool's purpose. The sibling tool is not referenced, but the name difference is self-explanatory.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema has zero parameters, so the baseline is 4 as per guidelines. The description adds no parameter-specific details because none are needed. It fully compensates for the absence of parameters by explaining the tool's output focus, which is sufficient.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's function: it returns reasons for not entering business mode, configuration path, and next steps in restricted mode. It uses a specific verb ('返回' meaning 'returns') and resource ('settings status'), distinguishing it from the sibling tool 'open_settings' which performs a different action (opening settings).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description specifies the context for use: '受限模式下' (in restricted mode), indicating when this tool is relevant. It does not explicitly mention alternatives or exclusions, but the behavior is clear enough that an agent can infer when to invoke it. The sibling tool's name 'open_settings' contrasts with the status-returning purpose, implicitly guiding selection.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

open_settingsA
Idempotent

内置工具，无法关闭；启动或复用本机设置页并返回访问地址。

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

TDQS

A4/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations provide idempotentHint=true and destructiveHint=false, and the description adds that the tool cannot be closed and may reuse an existing settings page. This provides useful behavioral context beyond the structured hints, with no contradiction.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

A single sentence front-loads the built-in/cannot-close caveat before stating the action and return value. Every phrase adds relevant information with no redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The tool is simple, parameterless, and has no output schema. The description explains the action, the return value (access address), and key behavioral constraints. It could be more specific about the address format, but it is adequate for this low-complexity tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool has zero parameters and schema description coverage is 100% (empty schema). With no parameters, the baseline is 4, and the description correctly implies no configurable inputs are needed.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses specific verbs ('启动或复用' = launch or reuse) and a clear resource ('本机设置页' = local settings page), and states it returns an access address. This distinguishes it from the sibling get_settings_status, which is a status check.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to use this tool versus get_settings_status. The note that it is built-in and cannot be closed is a constraint, not usage direction. No alternatives or exclusions are mentioned.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 2 tool updatesv0.1.2
    • First observedget_settings_status
    • First observedopen_settings
Deploy Server
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

A4/5.0

Scored across 2 tools

Disambiguation5/5

open_settings and get_settings_status are clearly distinct: one launches/reuses a settings page and returns a URL, while the other reports the status (why not in business mode, config path, next step). No overlap or confusion.

Naming Consistency5/5

Both tools follow a verb_noun snake_case pattern (open_settings, get_settings_status), providing a consistent and predictable naming convention.

Tool Count3/5

With only two tools, the server feels thin, especially for a settings-related domain. This is borderline but acceptable for a narrowly-focused utility.

Completeness2/5

The tool set covers opening settings and checking status but lacks any update, reset, or configuration modification tools. This leaves a significant gap for any agent needing to actually change settings, making the surface incomplete.

Maintenance

ActivityMaintained
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • Super Shell MCP Server

    cfdude
    A
    license
    A
    quality
    F
    maintenance
    An MCP server that enables secure execution of shell commands across Windows, macOS, and Linux with built-in whitelisting and approval mechanisms for enhanced security.
    9
    36 npm
    21
    MIT

  • pterodactyl-mcp

    mikketa
    A
    license
    A
    quality
    Not graded
    maintenance
    MCP server for Pterodactyl and Pelican game server panels. 73 tools for server management, power control, file operations, backups, schedules, databases, users, nodes, and eggs.
    34
    14 npm
    -

  • Minecraft Ops MCP

    damocjwj
    A
    license
    B
    quality
    D
    maintenance
    An MCP server for managing and operating Minecraft servers through multiple backend protocols including MCSManager API, RCON, and MSMP. It provides tools for instance lifecycle management, file operations, console commands, player administration, and server configuration with built-in security controls.
    71
    2
    MIT

  • Docker MCP Server

    0xshariq
    A
    license
    Not graded
    quality
    C
    maintenance
    A comprehensive MCP server that provides advanced Docker operations through a unified interface with 16 MCP tools and 25+ CLI aliases, enabling secure container lifecycle management, multi-container orchestration, registry publishing, and system maintenance.
    32 npm
    15
    ISC