SuperAPI AI Directory
Partner with us中文AI newsFavorites
Skillsbt-mcp-setup

bt-mcp-setup

Agents & models

View repository

Updated 10-15 21:48

About this skill

Baota Panel MCP Integration Installation and Configuration

Installation Prerequisites

  • An existing Baota Panel 13.0 official release (upgrade via [Update] in the top-right corner of the homepage)
  • Server terminal access (root or sudo)
  • Python runtime environment: 3.13
  • The Agent (Codex/ZCode/Kimi) must support remote MCP service connections (Streamable HTTP)
  • The Agent's network can reach the server's 8765 port (TCP)
  • Have a panel administrator account

Installation Steps (5 steps)

Step 1: Update the panel and Python

# 升级到 13.0 正式版（面板首页右上角【更新】）
Fresh installation of 13.0: download, verification, manual inspection, and execution must be kept separate

BT_INSTALLER="install13.sh" curl --fail --show-error --location --proto '=https' --tlsv1.2
--output "$BT_INSTALLER" https://download.bt.cn/install/install13.sh

Obtain the SHA-256 independently from the official Baota release page and fill it in; do not use unknown digests provided alongside the download page

BT_INSTALL_SHA256="<officially published SHA-256>" printf '%s %s\n' "$BT_INSTALL_SHA256" "$BT_INSTALLER" | shasum -a 256 -c -

Manually inspect the script contents and download domain, and only execute it separately after confirming there are no anomalies

less "$BT_INSTALLER" sudo bash "$BT_INSTALLER"

Upgrade Python to 3.13 in a non-panel terminal

bash /www/server/panel/script/upgrade_py313_bundle.sh


### 步骤 2：安装宝塔 MCP 服务

- 登录宝塔面板 → **软件商店** → 搜索"宝塔 MCP" → 找到【宝塔 MCP 服务】→ **安装**

### 步骤 3：放行 8765 端口（必须两处都放行）

**3a. 宝塔面板防火墙**：**安全**页面 → 入站规则 → 添加
- 协议：TCP
- 端口：8765
- 策略：accept

**3b. 云服务器厂商安全组/防火墙**：登录云厂商控制台，安全组添加入站规则同上

> ⚠️ 安全建议：仅放通 Agent 固定公网出口 IP，避免对所有来源开放（0.0.0.0/0）。

### 步骤 4：设置 IP 白名单

- MCP 插件 → **接入与体验** → 添加 Agent 公网出口 IP
- 仅支持**单个公网 IP**，不支持 IP 段
- Agent 公网 IP 可通过 `curl ifconfig.me` 查询

### 步骤 5：配置 Agent（不同客户端配置文件不同）

**方式 A：自动配置（推荐）**

- 接入与体验页面生成安装提示词 → 复制 → 发给 Agent
- Agent 会自动完成对应配置文件

**方式 B：手动配置**

参考 JSON 配置（Codex 风格）：

```json
{
  "mcpServers": {
    "baota-mcp": {
      "url": "https://<面板公网IP>:8765/bt-mcp-<实例标识>/mcp",
      "headers": {
        "Authorization": "Bearer <授权令牌>"
      },
      "disabled": false
    }
  }
}

Codex side：~/.codex/config.toml

[mcp_servers.baota-mcp]
url = "https://<面板公网IP>:8765/bt-mcp-<实例标识>/mcp"

[mcp_servers.baota-mcp.headers]
Authorization = "Bearer <授权令牌>"

ZCode/Kimi/Claude Code：~/.claude/mcp.json or plugin configuration

{
  "mcpServers": {
    "baota-mcp": {
      "url": "https://<面板公网IP>:8765/bt-mcp-<实例标识>/mcp",
      "headers": {
        "Authorization": "Bearer <授权令牌>"
      }
    }
  }
}

Key Parameters and Connection Information

Item Value/Description
Service port 8765（TCP）
Transport protocol HTTPS（Streamable HTTP）
Authentication method Bearer Token（Authorization request header)
Access path /bt-mcp-<实例标识>/mcp
Instance identifier Generated at installation (unique per panel instance)
Public network requirements Requires an HTTPS certificate (the panel SSL can be used to apply for an IP certificate)

HTTPS Certificate Requirements

Some systems require a valid HTTPS certificate chain. Path to apply for a trusted IP certificate:

  • Panel → Settings → Security settings → Panel SSL → Turn on panel SSL → Select IP certificate application entry

Do not disable HTTPS certificate verification; do not use a self-signed certificate (the Agent will reject it).

First Read-Only Verification Instruction

Have the Agent execute:

查看服务器当前状态，只读取 CPU、内存、磁盘、系统负载和服务运行情况，不要修改任何配置。

Expected: the Agent returns a structured server health report and does not trigger any modification operations.

Common Troubleshooting Table

Error Cause Handling
403 ip denied The Agent's public IP has not been added to the whitelist Add the current egress IP on the whitelist page
Prompt retrieval failed (certificate chain) The HTTPS certificate is not in effect Apply for and install a panel SSL certificate, then retry
HTTP 500 when retrieving access information Python has not been upgraded to 3.13 Run upgrade_py313_bundle.sh, uninstall and reinstall the MCP service
The Agent cannot connect Port not open/network unreachable Check port 8765 in sequence (firewall + security group), IP whitelist, address/token, and SSL certificate validity
Codex cannot see the MCP tools The configuration file is not in effect Restart Codex, create a new task, and enter /mcp
Suspected token leak Security incident Immediately regenerate authorization in the plugin, delete the old Token, and update the Agent configuration

Security recommendations

  1. Minimize the IP whitelist: allow only the necessary Agent IPs; do not open 0.0.0.0/0
  2. Back up the production environment first: back up the database and site files before operating
  3. Keep credentials confidential: MCP addresses and tokens are sensitive information; avoid committing them to public repositories
  4. Do not execute commands of unknown origin: commands suggested by the AI Agent should be manually reviewed before execution
  5. Retain manual confirmation for high-risk operations: operations such as deleting files, modifying firewalls, and restarting services
  6. Monitor abnormal access: regularly check the panel's MCP access logs

Template variables (filled in by the user during onboarding)

panel_public_ip: <用户宝塔面板公网 IP>  # 例：203.0.113.10
panel_port: 8765                         # MCP 默认端口
panel_ssl_enabled: true                  # 是否启用面板 SSL
mcp_instance_id: <实例标识>              # 安装时生成
bearer_token: <授权令牌>                 # 接入与体验页面获取
agent_public_ip: <Agent 公网 IP>          # 通过 curl ifconfig.me 获取

When to use

✅ Applicable:

  1. The user explicitly wants to securely install and configure multi-client access to BT Panel MCP.
  2. The necessary context has been provided or can be safely obtained, and a verifiable mcp-setup-plan。
  3. Needs to be executed with least privilege and in a rollback-capable manner, while retaining audit evidence.

⚠️ Clarify first:

  1. When the target environment, authorization boundary, or success criteria are missing, first provide a read-only hypothetical plan and list the missing items.
  2. When production environment changes are involved, first confirm backups, maintenance windows, and rollback paths.
  3. When the input may contain sensitive information, reference only field names and redacted fragments; do not copy complete credentials.

❌ Not to be used:

  1. Directly executing a script after download or disabling TLS certificate verification.
  2. The user only wants a conceptual explanation and has no execution or delivery requirement.
  3. Requests that require bypassing authentication, certificate verification, manual confirmation, or other security controls.

Workflow

Step 1: Confirm the target, environment, authorization scope, and immutable constraints; if information is insufficient, first produce a read-only version with assumptions.

Step 2: Inventory the current state and dependencies, read only the necessary data, and do not record tokens, passwords, Cookies, or complete personal data.

Step 3: Choose the path with the least impact, and clearly mark high-risk actions, external network calls, and reversible steps.

Step 4: Generate or execute mcp-setup-plan, binding each step to inputs, expected outputs, and failure conditions.

Step 5: Verify the structure, factual sources, and target state; do not fabricate success conclusions based on missing evidence.

Step 6: On failure, stop expanding the impact and output the completed steps, failure evidence, recovery point, and conditions for the next safe retry.

Step 7: Deliver a summary, verification evidence, remaining risks, and follow-up actions; production changes must state whether rollback has been verified.

Rules

  • Read-only by default; write operations, high-risk operations, and paid calls must obtain explicit authorization matching the action.
  • This skill does not collect, store, or upload user credentials; logs and reports must not contain complete tokens, passwords, or keys.
  • Do not disable TLS verification, do not execute scripts of unknown origin, and do not use pipes to download and execute directly.
  • Only mark real execution results as "completed"; plans, examples, and inferences must be explicitly labeled.
  • Prefer idempotent operations; when idempotency is not possible, first provide a dry run, backup, and rollback point.

Validation checklist

  • Objectives, environment, and authorization scope are all clearly stated.
  • HTTPS、白名单、令牌和只读连通性验证全部通过 Verified by reproducible evidence.
  • Sensitive data has been masked, and the output contains no complete credentials.
  • Failure and timeout paths are covered, and no infinite retries occur.
  • Change-type tasks include backup or rollback instructions.
  • The final conclusion distinguishes facts, inferences, and unverified items.

Gotchas

  1. Authorization does not equal reachability: when permissions exist but the network, certificates, or allowlist requirements are not met, you must still stop and report the connection evidence.
  2. A success code does not equal business success: you must check HTTPS、白名单、令牌和只读连通性验证全部通过, and cannot rely only on the command exit code or HTTP 200.
  3. Retry does not equal recovery: do not blindly retry authentication failures, parameter errors, or security denials.
  4. Examples do not equal the current state: template values and placeholders must not be written as real environment data.
  5. Output does not equal delivery: structural validation, risk description, and repeatable verification must also be completed.
  6. Do not copy across environments: when the operating system, version, region, and host capabilities differ, parameters must be reconfirmed.

Progressive materials

  • Before choosing a path, read references/decisions/decision-guide.md。
  • When encountering exceptions, timeouts, or partial success, read references/operations/failure-matrix.md。
  • Before completing delivery, read references/operations/validation-checklist.md。
  • When reproducible input is needed, refer in order to examples/basic.md、examples/failure.md、examples/advanced.md。