---
title: "使用 WorkBuddy 接入宝塔 MCP"
description: "介绍如何将宝塔 MCP 安装提示词发送给 WorkBuddy，完成 MCP 与 Skills 配置、连接验证和首次只读调用。"
---

> 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.

# 使用 WorkBuddy 接入宝塔 MCP

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

本文从**获取 MCP 安装提示词**开始介绍。尚未安装【宝塔 MCP 服务】或未完成端口、HTTPS 等准备工作的用户，请先参考[宝塔 MCP 安装指引](/ai-ops/mcp/installation)。本文截图使用 WorkBuddy v5.3.14，不同版本的界面和配置位置可能略有差异。

:::warning 安全提示
安装提示词可能包含 MCP 服务地址、Token 或其他授权信息。请仅将提示词发送给可信的 WorkBuddy 任务，不要粘贴到公开聊天、工单或代码仓库。文中的地址、配置路径和执行结果仅为示例，请勿照抄。
:::

## 开始前准备

开始配置前，请确认：

- 【宝塔 MCP 服务】已安装并处于“运行正常”状态
- 宝塔面板防火墙和云服务器安全组已放行 MCP 服务端口
- MCP 服务已配置客户端信任的有效 HTTPS 证书
- 已安装并登录 WorkBuddy

## 1. 获取 MCP 安装提示词

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

![在宝塔 MCP 服务中复制 WorkBuddy 安装提示词](/img/ai-ops/agent/workbuddy-mcp/copy-install-prompt.png)

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

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

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

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

WorkBuddy 会下载并读取提示词指向的安装文档，然后按照文档配置 MCP 和相关 Skills。执行过程中请留意 WorkBuddy 展示的下载地址、配置路径和权限请求，确认与当前宝塔 MCP 配置一致后再允许写入。

![WorkBuddy 下载并读取宝塔 MCP 安装文档](/img/ai-ops/agent/workbuddy-mcp/download-instructions.png)

:::danger 不要跳过 HTTPS 证书校验
如果 WorkBuddy 提示需要忽略证书校验，请停止执行，先为 MCP 服务配置客户端信任且覆盖访问地址的有效证书。不要使用关闭校验、忽略证书错误或安装来源不明根证书的方式绕过问题。
:::

## 3. 核对配置与验证结果

执行完成后，WorkBuddy 应返回类似结果：

- 已将宝塔 MCP 条目写入用户级或项目级 `.workbuddy/mcp.json`
- 已保留配置文件中原有的其他 MCP 服务
- Bearer Token 已写入但未在结果中完整显示
- MCP `initialize` 成功
- `tools/list` 成功，且未出现 TLS、`401` 或 `403` 错误
- 已按需安装相关 Skills

![WorkBuddy 完成宝塔 MCP 配置和连通性验证](/img/ai-ops/agent/workbuddy-mcp/configuration-complete.png)

截图中的示例将用户级 MCP 配置写入 `~/.workbuddy/mcp.json`，将 Skills 安装到 `~/.workbuddy/skills/`。WorkBuddy 也可能使用项目级 `.workbuddy/mcp.json`；实际路径应以当前版本和任务返回结果为准。

截图中的工具和 Skills 数量仅为当次环境的结果，实际数量以当前宝塔 MCP 和 Skill 版本为准。配置完成后，如果当前任务仍无法发现新增工具，请重启 WorkBuddy 或新建任务后再次检查。

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

在 WorkBuddy 中发送一条只读指令，例如：

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

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

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

首次验证通过后，再根据实际需要逐步尝试其他操作。涉及删除文件、修改防火墙、重启服务、安装软件等高风险操作时，应仔细核对 WorkBuddy 的操作计划并保留人工确认。

## 常见问题

### WorkBuddy 无法下载或读取安装文档

确认安装提示词中的下载地址完整且未过期，并检查 WorkBuddy 所在网络能否访问宝塔面板。遇到证书错误时，应修复 MCP 服务证书，不要关闭 HTTPS 校验。

### MCP 连接返回 `403 ip denied`

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

### MCP 连接返回 `401`

检查 WorkBuddy 配置中的 Bearer Token 是否与宝塔 MCP 当前授权信息一致。Token 已更新或疑似泄露时，应在宝塔 MCP 中重新生成授权信息，再更新 WorkBuddy 配置。

### 配置完成后看不到宝塔 MCP 工具

检查用户级或项目级 `.workbuddy/mcp.json` 中是否存在宝塔 MCP 条目，并确认没有覆盖原有配置。随后重启 WorkBuddy 或新建任务，再执行只读查询验证。

## 相关文档

- [宝塔 MCP 安装指引](/ai-ops/mcp/installation)
- [宝塔 MCP 介绍](/ai-ops/mcp)
- [使用 Codex 接入宝塔 MCP](/ai-ops/agent/panel-integration/codex-mcp)
- [使用 Claude Code 接入宝塔 MCP](/ai-ops/agent/panel-integration/claude-code-mcp)
- [使用 TRAE 接入宝塔 MCP](/ai-ops/agent/panel-integration/trae-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)
- [Agent 接入宝塔 MCP 与使用 Skills](/ai-ops/agent/panel-integration)

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