跳到主要内容
版本：latest

宝塔MCP安装指引

宝塔 MCP 服务可将宝塔面板的运维能力接入支持 MCP 的 Agent。安装完成后，Agent 可以通过授权的 MCP 服务查询和管理服务器。

首次使用前，可先阅读宝塔 MCP 介绍，了解它与宝塔 AI 助手的区别及工作方式。

安装建议

建议先在非生产环境完成安装和功能验证。生产环境操作前，请备份重要数据，并仅向可信 IP 开放 MCP 服务端口。

安装前准备​

开始安装前，请确认：

  • 已取得宝塔面板管理员权限和服务器终端权限
  • 面板版本为稳定版 12.0 或正式版 13.0
  • 面板运行环境已升级到 Python 3.13
  • Agent 支持连接远程 MCP 服务
  • Agent 所在网络可以访问服务器的 8765 端口

1. 更新面板和 Python​

如果当前面板版本已经满足要求，可直接更新 Python；否则请先安装或升级到宝塔面板 13.0。

已有面板升级到 13.0​

已有正式版面板的用户可在面板首页右上角点击【更新】按钮，升级到 13.0。

全新安装 13.0​

在服务器终端中执行：

curl -sSO http://download.bt.cn/install/install13.sh && bash install13.sh

更新 Python 到 3.13​

在非面板终端中执行：

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

也可以登录面板，点击右上角的【更新】按钮完成升级。

通过面板更新版本

升级完成后，可在面板首页确认当前版本。

在面板首页确认版本

2. 安装宝塔 MCP 服务​

  1. 登录宝塔面板
  2. 进入【软件商店】
  3. 搜索“宝塔 MCP”
  4. 找到【宝塔 MCP 服务】并点击【安装】

在软件商店安装宝塔 MCP 服务

3. 放行 8765 端口​

安装完成后，需要同时在宝塔面板防火墙和云服务器厂商的安全组或防火墙中放行 8765 端口。

宝塔面板防火墙​

进入【安全】页面，添加一条入站规则：

  • 协议：TCP
  • 端口：8765
  • 来源：优先填写 Agent 的固定公网出口 IP

在宝塔面板防火墙放行 8765 端口

云服务器防火墙​

如果服务器部署在云平台，还需要在云平台控制台的安全组或防火墙中放行 8765 端口。

在云服务器防火墙放行 8765 端口

提示

不建议将 8765 端口向所有来源开放。无法确认 Agent 出口 IP 时，可先临时放行完成连通性测试，测试结束后立即收紧规则。

4. 设置 IP 白名单​

  1. 在软件商店中打开【宝塔 MCP 服务】
  2. 进入【接入与体验】
  3. 按页面提示添加 Agent 的公网出口 IP

宝塔 MCP 服务接入设置

添加 Agent 的公网出口 IP

注意

IP 段放通暂不可用，请填写单个公网 IP。配置错误会导致 Agent 无法连接 MCP 服务。

5. 配置 Agent​

支持自动配置和手动配置两种方式，推荐优先使用自动配置。

方式一：使用提示词自动配置​

  1. 在插件的【接入与体验】页面生成并复制安装提示词
  2. 将提示词发送给需要接入的 Agent
  3. 按 Agent 的提示完成 MCP 服务安装与连接

复制 MCP 安装提示词

Agent 自动完成 MCP 配置

方式二：手动配置​

  1. 打开插件的【安全授权】页面
  2. 获取 MCP 服务器地址和授权令牌
  3. 将信息填入 Agent 的 MCP 配置文件

获取 MCP 服务器地址和授权信息

参考配置：

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

MCP 服务器地址和授权令牌属于敏感信息。请勿提交到公开代码仓库、粘贴到公开聊天或分享给无关人员。如怀疑令牌泄露，请立即在插件中重新生成授权信息。

6. 验证连接​

完成配置后，让 Agent 执行一项只读操作，例如查询服务器基本信息。如果 Agent 能正常返回服务器信息，即表示 MCP 服务已成功接入。

通过 Agent 调用宝塔 MCP 服务

申请可信 IP 证书​

部分系统需要有效的 HTTPS 证书链才能连接 MCP 服务。可在宝塔面板中申请可信 IP 证书：

  1. 进入【设置】→【安全设置】→【面板 SSL】
  2. 打开面板 SSL
  3. 选择 IP 证书申请入口并完成申请
  4. 安装证书后，重新获取 MCP 接入信息

进入面板 SSL 设置

申请可信 IP 证书

常见问题​

安装提示词获取失败，提示“未探测到有效证书链”或“HTTPS 未就绪”​

按照申请可信 IP 证书中的步骤申请并安装面板 SSL 证书，然后重新获取安装提示词。

获取接入信息时提示 HTTP 500​

确认面板运行环境已经升级到 Python 3.13。升级完成后，卸载并重新安装【宝塔 MCP 服务】插件。

Agent 无法连接 MCP 服务​

依次检查：

  1. 宝塔面板防火墙是否已放行 TCP 8765 端口
  2. 云服务器安全组或防火墙是否已放行 TCP 8765 端口
  3. Agent 的公网出口 IP 是否已加入插件白名单
  4. MCP 服务器地址和授权令牌是否填写正确
  5. 面板 SSL 证书是否有效