宝塔 MCP 怎么接入？Claude Code、Codex、TRAE 配置全过程

宝塔 MCP 是宝塔官方提供的 MCP（Model Context Protocol，模型上下文协议）服务，它通过标准化接口把宝塔面板的运维能力——查询服务器与服务状态、管理网站、数据库、防火墙、Docker 等——接入支持 MCP 的 AI Agent。接入分两部分：先在宝塔面板里安装【宝塔 MCP 服务】并拿到服务器地址和授权令牌，再到 Claude Code、Codex、TRAE 等客户端里填入配置。下面按「面板侧准备 → 获取接入信息 → 各 Agent 配置」的顺序讲全过程。

宝塔 MCP 是什么，和面板里的 AI 助手有什么不同

MCP 是一种用于连接 AI 应用与外部工具、数据和服务的开放协议。宝塔 MCP 服务把面板的运维能力接入支持 MCP 的 Agent，让用户可以在常用的 AI 工具里查询服务器状态，并执行经过授权的面板操作。它适合这些场景：

• 在支持 MCP 的 Agent 中查询服务器和服务状态
• 辅助完成网站、数据库、防火墙等面板运维工作
• 把宝塔面板能力接入已有的 AI 工作流
• 减少在多个管理界面之间切换、手动编写命令

它和面板内 AI 助手最直接的区别是「入口」：AI 助手在面板内使用，MCP 由外部 Agent 调用。

对比项	宝塔 AI 助手	宝塔 MCP
使用入口	宝塔面板内的 AI 功能	支持 MCP 的外部 Agent
主要用途	在面板内对话、诊断、分析和执行运维任务	将宝塔面板能力提供给外部 Agent 调用
接入方式	在面板中配置模型后使用	安装 MCP 服务并配置服务地址、授权令牌和 IP 白名单

两者可以并行使用：AI 助手提供面板内的一体化体验，MCP 负责连接外部 Agent。

接入前要满足哪些条件

开始前先确认这几点，缺一不可：

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

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

面板侧：装 MCP 服务、放行端口、设 IP 白名单

第 1 步：升级面板到 13.0 并更新 Python

已有正式版面板的用户，在面板首页右上角点【更新】升级到 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 服务

登录面板，进入【软件商店】，搜索「宝塔 MCP」，找到【宝塔 MCP 服务】并点击【安装】。

第 3 步：放行 8765 端口

安装完成后，需要在两个地方同时放行 8765 端口：

• 宝塔面板防火墙：进入【安全】页面添加一条入站规则，协议 TCP、端口 8765，来源优先填 Agent 的固定公网出口 IP。
• 云服务器防火墙：服务器部署在云平台时，还要在云平台控制台的安全组或防火墙中放行 8765 端口。

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

第 4 步：设置 IP 白名单

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

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

拿到服务器地址和授权令牌（两种方式）

MCP 服务器地址形如 https://<面板公网IP>:8765/bt-mcp-<实例标识>/mcp，认证方式是请求头 Authorization: Bearer <授权令牌>。获取方式有两种。

方式一：用安装提示词自动配置（推荐）。在插件的【接入与体验】页面生成并复制安装提示词，把它发送给需要接入的 Agent，让 Agent 按提示完成 MCP 服务安装与连接。

方式二：手动配置。打开插件的【安全授权】页面，获取 MCP 服务器地址和授权令牌，填入 Agent 的 MCP 配置文件。通用参考配置如下：

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

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

Claude Code 怎么接入

Claude Code 支持把安装提示词直接发给它完成自动配置，也可以命令行手动添加。

1. 在【接入与体验】里添加 Claude Code 当前使用的公网出口 IP，复制生成的安装提示词。
2. 先切换权限模式：Claude Code 的 Auto mode 可能把「修改自身 MCP 配置」「持久化配置」判定为高风险而拒绝写入，建议先切到 Manual mode（手动模式）或默认交互模式，让它在关键步骤请求确认。
3. 打开目标项目，把安装提示词完整粘贴并发送。Claude Code 会读取安装文档、识别配置位置并测试 MCP 地址连通性。
4. 核对并批准配置写入：确认写入的是当前项目或预期的用户范围、MCP URL 指向自己的宝塔 MCP 服务、认证方式为 Bearer Token、不会覆盖已有 MCP 配置。
5. 确认结果：initialize 成功、tools/list 成功且无 TLS、401、403 错误，即表示配置完成。

配置生效后，发一条只读指令验证，例如：

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

如果 Claude Code 能返回服务器资源与服务状态，说明接入成功。

需要命令行手动兜底时，推荐用本地范围命令：

claude mcp add --transport http --scope local baota-mcp \
  "https://<面板公网IP>:8765/bt-mcp-<实例标识>/mcp" \
  --header "Authorization: Bearer <授权令牌>"

命令中的 Token 会进入当前 Shell 历史记录。需要长期使用时，建议改用项目根目录的 .mcp.json 并引用环境变量 Bearer ${BAOTA_MCP_TOKEN}，避免把真实 Token 提交进代码仓库。

不要跳过 HTTPS 证书校验。如果 Claude Code 建议用 curl -k、关闭 TLS 校验或信任来源不明的证书，应停止执行，先为 MCP 服务配置客户端信任且覆盖访问地址的有效证书。

Codex 怎么接入

Codex 同样用安装提示词完成自动配置，配置默认保存在 ~/.codex/config.toml，采用 Streamable HTTP 和 Bearer Token 认证。

1. 在【接入与体验】添加 Codex 当前使用的公网出口 IP，复制安装提示词。
2. 在 Codex 中新建任务，把提示词完整粘贴并发送。Codex 会读取安装文档，按文档完成 MCP 和相关 Skills 配置。
3. 如果出现 403 ip denied，返回【接入与体验】把 Codex 当前公网出口 IP 加入白名单，再回到 Codex 发送「已放通，请重新验证」。
4. 确认返回结果：MCP initialize 成功、tools/list 成功、无 401/403、Bearer Token 认证通过。

为确保新配置生效，建议重启 Codex 客户端并新建任务，或输入 /mcp 确认宝塔 MCP 服务已连接。之后同样用只读指令做首次验证。

TRAE 怎么接入

TRAE 官方把 TRAE Work 和 TRAE IDE 分别提供，界面和 MCP 配置入口可能不同，本文步骤以 TRAE Work 为准。与 Claude Code、Codex 不同，当前版本的 TRAE 需要在界面里手动添加 MCP 配置。

1. 在【接入与体验】添加 TRAE 当前网络的公网出口 IP，复制安装提示词，发给 TRAE Work 中的新任务。
2. TRAE 会读取安装说明并验证连接，但会提示 MCP 配置需要手动添加。打开【设置 → MCP】，选择【本地】（也可选【云端】，本文以桌面端本地配置为例），点击右上角【添加】，选择手动配置打开 JSON 输入框。
3. 粘贴下面的配置，替换三个占位符——<面板公网IP>、<实例标识>、<授权令牌>：

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

4. 确认无误后点击【确认】。配置成功后 MCP 管理页应显示 baota-mcp，右侧开关处于启用状态，展开可看到工具列表。

粘贴后重点检查：JSON 使用英文双引号、URL 以 /mcp 结尾、Authorization 以 Bearer 开头、disabled 为 false、没有覆盖原有的其他 MCP 配置。Token 属于高敏感凭据，不要截图分享或把含真实 Token 的 JSON 保存到公开仓库。

首次验证同样发只读指令，若 TRAE 能返回服务器资源与服务状态，即接入成功。

宝塔 MCP 能调哪些工具，安全怎么兜底

宝塔 MCP 共提供 98 个工具，覆盖基础文件操作、网站、网络、数据库、服务、Docker、系统、软件、防火墙、Java、Node.js 项目等类别。工具按风险等级区分：

• low：只读/安全，例如查询网站列表、服务状态、系统信息
• medium：有副作用，例如创建网站、启停服务、安装软件
• high：高危（删除/覆盖/执行命令），调用前须二次确认

涉及删除文件、修改防火墙、重启服务、安装软件等高风险操作时，应仔细核对 Agent 的操作计划并保留人工确认。

MCP 和 Skill 的区别，要不要再装 Skill

MCP 和 Skill 是相互独立的机制：MCP 给 Agent 提供可调用的运维工具；Skill 则是告诉 Agent 怎么安全地部署、接入和使用 MCP，以及提供项目部署、故障排查等标准流程。当前宝塔面板 Skill 选择以 MCP 作为面板操作通道。

只配置 MCP 就能使用面板工具，安装 Skill 的主要价值是补充标准化的部署、接入、操作和排障流程。想让 Agent 获得更完整的自动化流程，可以再装宝塔面板 Skill，把下面的提示词发给 Agent：

请根据 https://skillhub.cn/install/skillhub.md，安装 @btpanel/btpanel。

也可以在终端用 Skills CLI 安装：

npx skills add aaPanel/btpanel-skills

常见问题怎么排查

• 安装提示词获取失败，提示「未探测到有效证书链」或「HTTPS 未就绪」：进入【设置 → 安全设置 → 面板 SSL】申请并安装可信 IP 证书，再重新获取安装提示词。
• 获取接入信息时提示 HTTP 500：确认面板运行环境已升级到 Python 3.13，升级完成后卸载并重新安装【宝塔 MCP 服务】。
• Agent 无法连接 MCP 服务：依次检查面板防火墙是否放行 TCP 8765 端口、云服务器安全组是否放行、Agent 公网出口 IP 是否加入白名单、地址和令牌是否填写正确、面板 SSL 证书是否有效。
• 403 ip denied：把 Agent 实际使用的公网出口 IP 加入白名单，不要把白名单长期设置为允许任意来源。
• 401：检查 Bearer Token 是否与当前授权信息一致；Token 更新或疑似泄露时，在宝塔 MCP 中重新生成授权信息再更新配置。
• TLS 或证书错误：配置客户端信任且覆盖访问地址的有效 HTTPS 证书，不要用 curl -k、关闭 TLS 校验或导入来源不明的证书。

以上版本要求（正式版 13.0、Python 3.13）、端口、配置路径和命令均截至本文发文日期（2026-09-18），以宝塔官方文档为准，详见宝塔 MCP 介绍、宝塔 MCP 安装指引和各客户端接入教程：Claude Code、Codex、TRAE。