宝塔面板 Mcp，支持日志查询、一键建站、网站管理

bt-panel-mcp-server

MCP 対応の AI アシスタントから、宝塔面板（BT Panel）を安全に操作できます。日常的な運用に適した高レベルのツールに加え、現在の公式 API ドキュメントに記載された操作を網羅したカタログも内蔵しています。まずインターフェースの定義を検索し、その後、制御された方法で呼び出します。

GitHub | npm | 宝塔公式 API ドキュメント

機能概要

機能領域	できること	利用可能なモード
サイト診断	サイトの一覧表示、Nginx／アプリケーション／パネルのログ読み取り、Web サイトのドメインとバックアップの照会	readonly / full
サーバーの監視	CPU、メモリ、ディスク、ネットワーク、システム負荷、パネル操作ログの確認	readonly / full
ファイルと設定の読み取り	指定した任意のファイルの読み取り、サイトの Nginx 設定の確認、行数を指定した大容量ログの切り出し	readonly / full
Web サイトのライフサイクル	サイトの作成、起動・停止、削除、メモと有効期限の設定、PHP バージョンとディレクトリ保護状態の照会	full
ドメインとバックアップ	ドメインの紐付け／解除、Web サイトのバックアップの一覧表示、作成、削除	full
ファイルと Nginx の書き込み	Web サイトのファイルまたは Nginx 設定の保存	full
公式 API の完全なカバー	内蔵された公式ドキュメントの 369 件の操作を検索・実行：システム、Web サイト、データベース、ファイル、スケジュールタスク、FTP、SSL/ACME、SSH セキュリティ、プッシュ、プロジェクトデプロイ、Java、Docker、リバースプロキシなど	カタログは readonly、呼び出しは full

デフォルトは readonly で、書き込みや管理操作は公開されません。BT_MODE=full を明示的に設定した場合にのみ、すべての管理機能が有効になります。

公式 API の対象範囲

内蔵カタログは、宝塔公式 API ドキュメントの現在の検証済み基準（パネル v11.7.0、ドキュメントのコミット 1f8efe62fa9757d71a7259b063bd63e3775e2e3c）に基づいており、369 件の実行可能な操作を含みます。数百のツールをクライアントに一度に詰め込むのではなく、以下の安定した手順を提供します。

search_bt_api  ->  get_bt_api_operation  ->  call_bt_api
查找能力           核对参数和路由              在 full 模式执行

公式モジュール	主な機能
システム管理	CPU／メモリ／ディスク／ネットワーク、サービスの起動・停止、パネルの再起動、アップグレード、クリーンアップ、デーモンタスク
Web サイト管理	サイトの作成と削除、SSL/HTTPS、リライト、実行ディレクトリ、トラフィック制限、リバースプロキシ、リダイレクト、セキュリティレスポンスヘッダー
データベース	データベースとユーザー、バックアップ、インポート状態、スロークエリログ、エラーログ、Binlog、MySQL の設定と状態
ファイル	ファイルとディレクトリの閲覧、読み書き、コピー、アップロード、解凍、ごみ箱、ファイル履歴、権限、Webshell スキャン
スケジュールタスクと FTP	スケジュールタスクの追加・削除・変更・照会、実行ログ、ログローテーション、自動バックアップ、FTP ユーザーと権限の管理
証明書とセキュリティ	SSL オーダーと証明書、ACME の申請と更新、DNS API、SSH セキュリティ設定とセキュリティスキャン
プロジェクトとコンテナ	プロジェクトのデプロイ、Java/Tomcat/Spring Boot、Docker コンテナ／イメージ／ネットワーク／ボリューム／アプリストア、リバースプロキシプラグイン
その他	プッシュ、バックグラウンドタスク、Web SSH ターミナル設定、パスワード管理、リスクスキャン

カタログがカバーするのは、公式ドキュメントに記載された操作の定義です。対象のパネルで実際に実行できるかどうかは、パネルのバージョン、プラグインのインストール状況、API の許可リスト、アカウント権限、パラメーターの有効性によって異なります。

ツール一覧

readonly モード

ツール	説明
list_sites	宝塔で管理されている Web サイトを一覧表示し、名前またはドメインで検索します
get_nginx_logs	指定したサイトの Nginx アクセス／エラーログを読み取ります。パスの自動検出に対応しています
get_app_logs	Laravel、ThinkPHP、Java、Node.js など、一般的なアプリケーションのログを検索して読み取ります
get_panel_logs	パネル操作ログを照会し、監査やトラブルシューティングに使用します
get_system_status	CPU、メモリ、ディスク、ネットワーク、システム負荷を集約して表示します
read_file	サーバー上の指定ファイルを読み取ります。最後の N 行に制限できます
get_nginx_config	サイトの Nginx 仮想ホスト設定を読み取ります
list_domains	サイトに紐付けられたドメインとポートを照会します
list_backups	サイトのバックアップ記録を照会します
search_bt_api	369 件の公式 API 操作を検索し、モジュール、操作名、説明で絞り込みます
get_bt_api_operation	公式操作の HTTP メソッド、パス、固定 action、必須パラメーター、説明を返します

full モードで追加されるツール

ツール	説明	リスクに関する注意
manage_sites	サイトの作成、起動・停止、削除、メモと有効期限の設定	オプションで、ディレクトリ、データベース、FTP も併せて削除できます
manage_domains	ドメインの紐付けまたは解除	サイトにアクセスできるドメインに影響します
manage_backups	Web サイトのバックアップを作成または削除します	削除後は復元できない場合があります
save_nginx_config	サイトの Nginx 設定を上書きします	保存後、サイトのサービスに直ちに影響します
save_file	サーバー上の指定ファイルを上書きします	アプリケーションの実行に影響したり、機密情報が漏えいしたりする可能性があります
call_bt_api	内蔵された公式カタログの任意の操作を実行します	削除、再起動、アップグレード、証明書、コンテナ、データベースなどの高リスク操作が含まれます

BT_API_KEY、request_time、request_token、およびカタログで定義された action は、MCP 呼び出し元から受け付けません。すべてサーバー側で生成または注入されます。

クイックスタート

1. 宝塔 API を有効にする

宝塔パネルにログインし、「設定」->「一般設定」を開きます。

1. パネルポートを控えます。例：35335。
2. セキュリティエントリを控えます。例：/a5cbfadd。これは BT_PANEL_URL に含める必要がありますが、API リクエストはサイトのルートパスから自動的に送信されます。
3. API インターフェースを開き、インターフェースキーをコピーして、MCP の実行ホストの IP を API の許可リストに追加します。

2. MCP クライアントを設定する

npx を使った実行を推奨します。

{
  "mcpServers": {
    "bt-panel": {
      "command": "npx",
      "args": ["-y", "bt-panel-mcp-server"],
      "env": {
        "BT_PANEL_URL": "https://服务器IP:面板端口/安全入口",
        "BT_API_KEY": "你的API密钥",
        "BT_MODE": "readonly"
      }
    }
  }
}

ローカルソースから実行する場合は、args を本プロジェクトの dist/index.js の絶対パスに変更します。設定ファイルの場所は Cursor、Claude Desktop、Windsurf、Cherry Studio、Cline などのクライアントによって異なります。各クライアントの MCP 設定画面を使用してください。

3. まず読み取り専用で接続を確認する

MCP クライアントを再起動した後、まず AI に次の操作を実行させます。

列出宝塔面板的所有网站，并告诉我当前服务器 CPU、内存和磁盘使用情况。

成功したら、必要に応じて BT_MODE を full に変更し、クライアントを再起動します。影響範囲を理解していない状態で、AI にサービスの削除、アップグレード、再起動を直接指示しないでください。

環境変数

変数	必須	デフォルト値	説明
BT_PANEL_URL	はい	-	パネルのアドレス。例：https://192.0.2.10:35335/a5cbfadd。ポートとセキュリティエントリに対応しています
BT_API_KEY	はい	-	宝塔 API インターフェースキー。MCP サーバーの環境変数にのみ設定してください
BT_MODE	いいえ	readonly	readonly は照会／カタログツールのみを公開します。full はすべての管理操作と公式 API 呼び出しを公開します
BT_ALLOW_INSECURE_TLS	いいえ	false	接続先が信頼でき、有効な証明書を設定できないと確認できた場合にのみ true にします。本番環境では TLS 検証を有効にしてください

セキュリティエントリ、API キー、パスワード、トークン、証明書の秘密鍵、データベースの認証情報を、自然言語のプロンプト、URL、ブラウザーコード、Git リポジトリに記載しないでください。

公式 API カタログを使う

機能を検索する

たとえば、AI に Docker コンテナ、データベース、証明書に関する操作を検索させます。

搜索宝塔官方 API 中与 Docker 容器列表有关的操作，列出可用 ID 和必填参数。

search_bt_api を直接呼び出すこともできます。

{ "query": "容器列表", "module": "docker", "include_parameters": false }

获取准确参数

对要执行的操作先调用 get_bt_api_operation：

{ "operation": "database/GetDatabasesList" }

返回结果会包含请求方法、路径、固定 action、必填参数、类型和官方说明。不要根据猜测拼参数。

执行操作

确认目的和参数后，在 BT_MODE=full 下调用 call_bt_api：

{
  "operation": "database/GetDatabasesList",
  "params": {
    "p": 1,
    "limit": 20,
    "sid": 0
  }
}

对于带密码、私钥、DNS API Key 或容器配置的操作，params 仍可能包含敏感数据；仅在用户已明确授权向其自己的宝塔面板发送这些值时执行。

常见工作流

故障排查

1. 列出站点并确认目标名称
2. 读取最近 200 行 Nginx error 日志
3. 读取应用日志，比较同一时间段的异常
4. 查询系统负载、内存、磁盘和网络
5. 只在原因明确后修改配置；修改前先读取原文件并保留回滚内容

可直接对 AI 说：

排查 example.com 最近的 502：先看 Nginx 错误日志、再看应用日志和系统负载；只报告证据，不修改任何配置。

建站和内容发布

1. 用 manage_sites 创建站点和目录
2. 用 list_domains / manage_domains 核对域名绑定
3. 用 save_file 写入 index.html 或应用配置
4. 用 get_nginx_config 复核虚拟主机配置
5. 在公网或目标网络访问站点，确认 HTTP 状态、证书和内容

数据库、证书、Docker 或计划任务

1. search_bt_api 找到准确的官方操作
2. get_bt_api_operation 读取参数、前置条件与影响范围
3. full 模式下 call_bt_api 执行
4. 再用对应查询操作验证最终状态、日志或任务结果

涉及删除、覆盖、重启、升级、清理 Binlog、证书替换、容器删除或数据库用户权限变更时，应先说明目标对象、影响范围和回滚方式，再执行。

边界与安全模型

• readonly 不提供写入和官方 API 调用，但 read_file 仍能读取指定文件；不要读取无关的 .env、私钥或凭据文件。
• full 是权限开关，不是自动授权。执行破坏性操作前应取得针对具体目标的明确许可。
• call_bt_api 只允许调用内置官方目录中的操作，不接受任意 URL、任意 HTTP 方法或用户自定义 action。
• API 目录来自文档，不是目标主机的能力探测。某些 Docker、Java、反向代理、SSL 或商业插件接口在未安装时会失败。
• HTTPS 默认验证服务端证书。自签名证书需要显式设置 BT_ALLOW_INSECURE_TLS=true，此时应确保访问网络可信。
• API 接口可能随宝塔面板版本变更；每次面板大版本升级后，应先在测试环境验证关键调用。

常见问题

提示 Missing required environment variables

检查 MCP 进程环境中是否同时有 BT_PANEL_URL 和 BT_API_KEY，修改后完全重启客户端。

请求超时、403 或 API 白名单错误

确认面板地址/端口正确，MCP 主机 IP 已加入 API 白名单，且防火墙、安全组允许访问面板端口。安全入口需要写入 BT_PANEL_URL。

HTTPS 连接报证书错误

优先为面板配置可信证书。只有在确认内网链路和目标身份可信时才设置 BT_ALLOW_INSECURE_TLS=true。

官方操作执行失败

先用 get_bt_api_operation 重查参数，再确认面板版本、对应插件、账户权限和 API 白名单。文档目录覆盖不保证旧版本面板或未安装插件支持该操作。

full 模式有什么风险

它可以修改站点、配置、文件、数据库、证书、容器和系统服务。对生产环境应保持备份、先读取现状、执行后独立验证，并保留回滚内容。

本地开发与目录更新

npm ci
npm run build
node dist/index.js

更新官方目录时，先获取 cnb.cool/btpanel/docs，再运行：

$env:BT_OFFICIAL_DOCS_DIR = 'D:\src\btpanel-docs'
$env:BT_OFFICIAL_DOCS_REVISION = (git -C $env:BT_OFFICIAL_DOCS_DIR rev-parse HEAD)
npm run generate:api-catalog
npm run build

生成后应检查操作数量、抽查 GET/POST 路由和必填参数，再在目标面板或测试面板验证重点插件接口。

技术栈

• TypeScript
• Node.js >= 20
• @modelcontextprotocol/sdk
• 宝塔官方 API 文档目录生成器

License

MIT