跳到主要内容
版本：latest

使用 TRAE 接入宝塔 MCP

将宝塔 MCP 接入 TRAE 后，可以在 TRAE 任务中查询服务器状态，并按需调用网站、数据库、Docker、安全等宝塔面板能力。

本文从获取 MCP 安装提示词开始介绍，截图使用 TRAE Work。TRAE 官方将 TRAE Work 和 TRAE IDE 分别提供下载，两者的界面和 MCP 配置入口可能不同；本文步骤以截图所示的 TRAE Work 为准。TRAE 官方也说明 Agent 可以通过 MCP 按需访问外部资源，相关能力和界面仍可能随版本更新，具体以当前客户端显示为准。

安全提示

安装提示词和手动配置中可能包含 MCP 服务地址、Token 或其他授权信息。请仅在可信任务中使用，不要粘贴到公开聊天、工单或代码仓库。本文截图已对用户头像、昵称、Token 和实例化地址进行脱敏，配置示例也只使用占位符。

开始前准备​

开始配置前，请确认：

  • 【宝塔 MCP 服务】已安装并处于“运行正常”状态
  • 宝塔面板防火墙和云服务器安全组已放行 MCP 服务端口
  • MCP 服务已配置客户端信任且覆盖访问地址的有效 HTTPS 证书
  • 已安装并登录 TRAE Work
  • 已获取 TRAE 当前网络的公网出口 IP

1. 获取 MCP 安装提示词​

  1. 登录宝塔面板，进入【软件商店】
  2. 打开【宝塔 MCP 服务】的设置页面
  3. 进入【接入与体验】
  4. 点击【配置 IP 白名单】，添加 TRAE 当前使用的公网出口 IP
  5. 复制页面生成的 MCP 安装提示词

在宝塔 MCP 服务中复制 TRAE 安装提示词

提示

TRAE 所在网络的公网出口 IP 可能发生变化。如果后续出现 403 ip denied，请重新确认实际出口 IP，并更新 MCP 服务白名单。

2. 将安装提示词发送给 TRAE​

在 TRAE Work 中新建任务，将刚才复制的安装提示词完整粘贴到输入框并发送。

将宝塔 MCP 安装提示词发送给 TRAE Work

TRAE 会读取提示词指向的安装文档，并检查 MCP 地址、鉴权方式和连通性。在本文实测版本中，TRAE 可以读取安装说明和验证连接，但提示 MCP 配置需要由用户在界面中手动添加。

TRAE 提示需要在界面中手动添加 MCP 配置

如果当前版本能够直接引导打开 MCP 设置，也应先核对服务地址、认证方式和配置范围，再确认操作。不要要求 Agent 绕过产品的安全限制直接修改自身配置。

不要跳过 HTTPS 证书校验

截图中的一次任务输出提到了 tls_required=false，这只是当次测试环境的结果，不是推荐配置。应为 MCP 服务配置客户端信任且覆盖访问地址的有效证书；不要关闭 TLS 校验、忽略证书错误或导入来源不明的根证书。

3. 打开 MCP 设置​

  1. 打开 TRAE Work 设置
  2. 在左侧选择【MCP】
  3. 根据需要选择【本地】或【云端】；本文以桌面端本地配置为例，选择【本地】
  4. 点击右上角【添加】

在 TRAE Work 设置中打开本地 MCP 管理

在添加菜单中选择手动配置，打开 JSON 输入框。

在 TRAE Work 中打开 MCP 手动配置输入框

4. 粘贴宝塔 MCP 配置​

将下面的配置复制到手动配置输入框，并替换其中三个占位符：

  • <面板公网IP>：宝塔 MCP 对外提供服务的公网 IP 或域名
  • <实例标识>：当前宝塔 MCP 实例的路径标识
  • <授权令牌>：当前实例生成的完整授权 Token
{
  "mcpServers": {
    "baota-mcp": {
      "url": "https://<面板公网IP>:8765/bt-mcp-<实例标识>/mcp",
      "headers": {
        "Authorization": "Bearer <授权令牌>"
      },
      "disabled": false
    }
  }
}

在 TRAE Work 中粘贴宝塔 MCP JSON 配置

粘贴后重点检查：

  • JSON 使用英文双引号，且没有注释或多余逗号
  • URL 指向自己的宝塔 MCP 服务，路径以 /mcp 结尾
  • Authorization 的值以 Bearer 开头，后面紧跟完整 Token
  • disabled 为 false
  • 没有覆盖原有的其他 MCP 配置

确认无误后点击【确认】。Token 属于高敏感凭据，不要截图分享，也不要把包含真实 Token 的 JSON 保存到公开仓库。

5. 确认 MCP 和工具状态​

配置成功后，MCP 管理页应显示 baota-mcp。确认右侧开关处于启用状态，并展开服务查看工具列表。

TRAE Work 已连接宝塔 MCP 并显示工具列表

工具名称和数量会随宝塔 MCP 版本、授权范围和服务状态变化。只要服务状态正常、所需工具可见，且未出现 401、403 或证书错误，即可继续验证。

如果列表没有立即刷新，可以点击页面右上角的刷新按钮，或关闭设置后重新打开。当前任务如果早于 MCP 配置创建，也可以新建任务后再次检查。

6. 执行首次只读验证​

新建 TRAE 任务，发送一条只读指令，例如：

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

如果 TRAE 能调用宝塔 MCP 并返回服务器资源与服务状态，说明接入成功。

通过 TRAE Work 查询宝塔服务器状态

截图中的资源数据、IP、工具数量和运行时长仅为当次测试结果。首次验证通过后，再根据实际需要逐步尝试其他操作。涉及删除文件、修改防火墙、重启服务、安装软件等高风险操作时，应仔细核对操作计划并保留人工确认。

常见问题​

TRAE 提示必须通过界面添加 MCP​

这是当前实测版本的安全行为。按照本文步骤进入【设置 > MCP > 本地 > 添加 > 手动配置】，粘贴 JSON 后确认即可。不要通过修改未知内部文件或关闭安全检查来绕过界面限制。

配置保存后看不到宝塔 MCP​

检查 JSON 是否完整、mcpServers 和 baota-mcp 层级是否正确，并确认 disabled 为 false。随后刷新 MCP 列表；仍未出现时，关闭并重新打开 TRAE Work 后再次添加。

MCP 已显示但没有工具​

确认 baota-mcp 右侧开关已开启，然后展开服务查看工具列表。可以点击刷新按钮或新建任务，让客户端重新加载 MCP 工具。

MCP 连接返回 403 ip denied​

返回【宝塔 MCP 服务】的【接入与体验】页面，将 TRAE 当前使用的公网出口 IP 加入白名单。不要将白名单长期设置为允许任意来源。

MCP 连接返回 401​

检查 Authorization 请求头是否使用 Bearer <授权令牌> 格式，以及 Token 是否与当前宝塔 MCP 实例一致。Token 已更新或疑似泄露时，应在宝塔 MCP 中重新生成授权信息，再更新 TRAE 配置。

出现 TLS 或证书错误​

为 MCP 服务配置客户端信任且覆盖访问地址的有效 HTTPS 证书，并确认系统时间和证书链正常。不要关闭 TLS 校验或忽略证书错误。

关于 Skill​

宝塔 MCP 和宝塔面板 Skill 是相互独立的机制。仅配置 MCP 即可在 TRAE 中使用面板工具；如果当前 TRAE 版本支持安装 Skills，并希望获得更完整的部署、排障和安全操作流程，可以再单独安装宝塔面板 Skill。安装方法请参考宝塔面板 Skill 安装与使用指引。

相关文档​