2.2 安装宝塔 MCP：五步走

2.2 安装宝塔 MCP：五步走

安装前确认清单

先对清单，再动手。官方明确列出的安装前准备如下，建议逐项打勾：

确认项	要求	状态
面板权限	已取得宝塔面板管理员权限	□
终端权限	已取得服务器终端权限（可通过 SSH 登录）	□
面板版本	面板版本为正式版 13.0	□
运行环境	面板运行环境已升级到 Python 3.13	□
Agent 支持	Agent 支持连接远程 MCP 服务	□
网络可达	Agent 所在网络可以访问服务器 8765 端口	□

官方还有三条建议，请务必当回事：

先在非生产环境完成安装和功能验证，跑通了再上生产；
生产环境操作前备份重要数据；
仅向可信 IP 开放 MCP 服务端口。

这三条不是客套话。MCP 连上之后，Agent 是能对服务器做管理操作的，你的权限边界就是这套防火墙、白名单和令牌。宁可慢一步，不要裸奔一步。

五步总览：先看全貌

正式动手前，先把五步摊开看一遍，心里有张地图：

步骤	在哪操作	做完得到什么
1. 更新面板与 Python	面板首页右上角【更新】/ 服务器终端	正式版 13.0 + Python 3.13
2. 安装 MCP 服务	面板【软件商店】	【宝塔 MCP 服务】插件
3. 放行 8765 端口	面板防火墙 + 云安全组	TCP 8765 入站可达
4. 设置 IP 白名单	插件【接入与体验】	Agent 出口 IP 进门禁
5. 配置 Agent 并验证	插件 + 你的 Agent	MCP 连接打通

五步有依赖关系：Python 不升级，后面可能直接卡在 HTTP 500；端口和白名单只做一半，Agent 就进不来。所以别跳步，按顺序来。

整套流程走下来，熟练之后每步都是几分钟的事，第一次装建议留出完整一段不被打扰的时间，尤其是升级 Python 和装插件这两步，中途中断容易留下半安装状态。

第一步：更新面板到 13.0 与 Python 3.13

先说版本背景，方便你理解为什么非得是 13.0：宝塔面板有稳定版和正式版两条线，稳定版 12.0.0 是纯净版，无 AI 功能、免绑定账号、无付费广告，适合公司生产环境；正式版 13.0 才带 AI 功能，面板 AI 功能适用 v11.7 及以上版本。要用 MCP，就走正式版 13.0。

分两种情况操作：

已有正式版面板的，登录面板首页，点右上角【更新】，按提示升级到 13.0 即可；全新安装则在服务器终端执行：

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

接着升级 Python。这一步有个容易踩的坑：要在非面板终端里执行，别在面板自带的终端窗口跑：

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

当然，也可以登录面板点右上角【更新】来完成升级。升级完成后，回面板首页确认版本号显示正常，确认到位再往下走。这一步是整个安装的地基，Python 版本不对，后面获取接入信息时可能直接报 HTTP 500，所以宁可在这里多花一分钟。

第二步：软件商店安装【宝塔 MCP 服务】

路径很直白：登录面板 →【软件商店】→ 搜索“宝塔 MCP”→ 找到【宝塔 MCP 服务】→ 点【安装】。整个安装过程由面板自动完成，等进度跑完，插件出现在软件商店的已安装列表里，这一步就成了。后面第三步、第四步都要从这个插件入口进，建议先把位置记住。

第三步：放行 8765 端口

MCP 服务走 TCP 8765 端口。这个端口要同时放行两处，只放一处等于没放：

放行位置	操作路径	要点
宝塔面板防火墙	【安全】页面添加入站规则	协议 TCP、端口 8765
云平台安全组	云服务器厂商控制台	同样放行 TCP 8765 入站

两层防火墙的关系可以这么理解：云安全组是机房大门，面板防火墙是屋子房门，MCP 的流量两层都得过。不同云厂商控制台界面叫法不一，但都有安全组或防火墙入口，找到入站规则照加即可。

来源地址优先填 Agent 的固定公网出口 IP，不建议向所有来源开放。如果暂时确认不了 Agent 的出口 IP，可以先临时放行做连通性测试，测完立即收紧。临时放行期间，服务器暴露面是放大的，别拖太久。

第四步：设置 IP 白名单

端口通了，还要过白名单。入口：软件商店打开【宝塔 MCP 服务】→【接入与体验】→ 按提示添加 Agent 的公网出口 IP。

两个注意点：

IP 段放通暂不可用，只能填单个公网 IP。Agent 有多个出口 IP，就逐个都加进去；
配置错误会导致 Agent 无法连接。后面连不上时，第一个要查的就是这里。

端口和白名单是配合关系：端口决定流量能不能到服务器，白名单决定到了之后认不认这个来源。打个比方，端口是敞开的门，白名单是门禁名单——门开着但不在名单上，照样进不来。所以两步都得做，且白名单尽量精确到单个 IP，这才是官方说的仅向可信 IP 开放。

第五步：配置 Agent 并验证连接

最后一步是把 Agent 接进来，两种方式：一是插件【接入与体验】页生成并复制安装提示词，发给要接入的 Agent，按提示完成安装与连接；二是【安全授权】页获取 MCP 服务器地址和授权令牌，手动填进 Agent 的 MCP 配置文件。

具体怎么配，2.3 专门讲，本篇点到为止。配置完成后做一次验证：让 Agent 执行一项只读操作，比如查询服务器基本信息，能正常返回即成功。

请查询这台服务器的基本信息：系统版本、CPU、内存、磁盘使用情况。只做查询，不要执行任何修改。

为什么强调只读？因为这是风险最小的一步。只读查询能通，说明网络、白名单、令牌、Agent 配置整条链路全部正常；第一次连接就让 Agent 干活，万一路由错了、权限大了，代价可能是生产数据。先只读，后动手，这个顺序贯穿全书。

常见问题速查

装的过程中遇到卡壳，先查这张表，能省很多事：

现象	原因与处理
获取安装提示词失败，提示“未探测到有效证书链”或“HTTPS 未就绪”	需要申请可信 IP 证书：【设置】→【安全设置】→【面板 SSL】→ 打开面板 SSL → 选择 IP 证书申请入口完成申请 → 安装证书后重新获取 MCP 接入信息
获取接入信息时 HTTP 500	确认面板运行环境已升级 Python 3.13；升级后卸载并重新安装【宝塔 MCP 服务】插件
Agent 无法连接 MCP 服务	依次检查：① 面板防火墙是否放行 TCP 8765；② 云服务器安全组是否放行；③ Agent 公网出口 IP 是否在插件白名单；④ 服务器地址和授权令牌是否正确；⑤ 面板 SSL 证书是否有效

证书这条值得多说一句：部分系统需要有效的 HTTPS 证书链才能连接 MCP。如果你在获取接入信息时被证书挡住，按上表路径申请并安装面板 SSL 证书，然后重新获取接入信息即可。这也是官方单独列出的一个流程，说明踩的人不少。

排查这类问题建议按链路走：从 Agent 侧往服务器侧逐段确认——Agent 配置对不对，出口 IP 在白名单里吗，端口通不通，证书是否有效。最怕的是四处乱改，改完自己也说不清哪一步生效了。每验证通一段，就固定一段的配置，后面再出问题范围就小了很多。

小结

五步走复盘：更新面板与 Python → 软件商店装插件 → 放行 8765 端口 → 设 IP 白名单 → 配置 Agent 并验证。每一步都不难，难的是按顺序做全，尤其是端口要面板防火墙和云安全组两处都改。

给生产环境站长的建议：拿一台非生产的机器先完整走一遍，确认 Agent 能查能管、各项限制符合预期，再把同样配置搬到生产服务器，操作前照例备份重要数据。这套流程走顺之后，后面加新 Agent、加新服务器，都是重复劳动。

如果你还没有面板，可以先用快速安装宝塔面板把面板装上，注意 MCP 需要正式版 13.0。更细的官方步骤与截图说明，见宝塔 MCP 安装指引；想整体了解宝塔 AI 能力版图，可以读AI 运维总览。装好之后，2.3 我们细讲 Agent 侧的两种配置方式。