BT Ops MCP

概要

非公式の独立プロジェクト — 宝塔パネル公式との提携や推薦関係はありません。

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 つの中核的な能力領域を網羅し、さらに MCP 自体を管理する 4 個のツールを備え、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