---
title: "使用 TRAE 接入宝塔 MCP"
description: "介绍如何在 TRAE Work 中手动添加宝塔 MCP 配置，完成连接检查、工具确认和首次只读调用。"
---

> Documentation Index
> Fetch the complete documentation index at: https://docs.bt.cn/llms.txt
> Use this file to discover all available pages before exploring further.

# 使用 TRAE 接入宝塔 MCP

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

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

:::warning 安全提示
安装提示词和手动配置中可能包含 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 安装提示词](/img/ai-ops/agent/trae-mcp/copy-install-prompt.png)

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

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

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

![将宝塔 MCP 安装提示词发送给 TRAE Work](/img/ai-ops/agent/trae-mcp/submit-install-prompt.png)

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

![TRAE 提示需要在界面中手动添加 MCP 配置](/img/ai-ops/agent/trae-mcp/manual-configuration-required.png)

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

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

## 3. 打开 MCP 设置

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

![在 TRAE Work 设置中打开本地 MCP 管理](/img/ai-ops/agent/trae-mcp/open-mcp-settings.png)

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

![在 TRAE Work 中打开 MCP 手动配置输入框](/img/ai-ops/agent/trae-mcp/open-manual-config.png)

## 4. 粘贴宝塔 MCP 配置

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

- `<面板公网IP>`：宝塔 MCP 对外提供服务的公网 IP 或域名
- `<实例标识>`：当前宝塔 MCP 实例的路径标识
- `<授权令牌>`：当前实例生成的完整授权 Token

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

![在 TRAE Work 中粘贴宝塔 MCP JSON 配置](/img/ai-ops/agent/trae-mcp/paste-mcp-json.png)

粘贴后重点检查：

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

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

## 5. 确认 MCP 和工具状态

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

![TRAE Work 已连接宝塔 MCP 并显示工具列表](/img/ai-ops/agent/trae-mcp/mcp-tools-available.png)

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

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

## 6. 执行首次只读验证

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

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

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

![通过 TRAE Work 查询宝塔服务器状态](/img/ai-ops/agent/trae-mcp/first-readonly-check.png)

截图中的资源数据、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 安装与使用指引](/ai-ops/agent/panel-integration/skill-installation)。

## 相关文档

- [宝塔 MCP 安装指引](/ai-ops/mcp/installation)
- [宝塔 MCP 介绍](/ai-ops/mcp)
- [使用 Codex 接入宝塔 MCP](/ai-ops/agent/panel-integration/codex-mcp)
- [使用 WorkBuddy 接入宝塔 MCP](/ai-ops/agent/panel-integration/workbuddy-mcp)
- [使用 Claude Code 接入宝塔 MCP](/ai-ops/agent/panel-integration/claude-code-mcp)
- [使用 DeepSeek Harness 接入宝塔 MCP](/ai-ops/agent/panel-integration/deepseek-harness-mcp)
- [通过 Hermes 与 OpenClaw 消息通道接入宝塔 MCP](/ai-ops/agent/panel-integration/hermes-openclaw-mcp)
- [宝塔面板 Skill 安装与使用指引](/ai-ops/agent/panel-integration/skill-installation)
- [TRAE 官方产品介绍](https://www.trae.ai/ide/)
- [TRAE 官方更新日志](https://www.trae.ai/changelog)
- [Agent 接入宝塔 MCP 与使用 Skills](/ai-ops/agent/panel-integration)

Source: https://docs.bt.cn/ai-ops/agent/panel-integration/trae-mcp/index.mdx