WorkBuddy 配置 3CX MCP 教程

3CX MCP 可以把 3CX PBX 中的分机、通话等信息作为工具提供给 AI。完成配置后，可直接在 WorkBuddy 中通过自然语言查询 PBX，例如“PBX 中有多少分机？”。

本文参考 3CX 官方 MCP 配置文档，介绍如何在 WorkBuddy 中添加、授权并验证 3CX MCP。

一、准备工作

开始前，请确认以下条件已经满足：

• 3CX PBX 可从公网访问。
• 3CX 已提供 MCP 客户端功能。
• 准备一个能够登录 3CX 并授权 MCP 的用户账号。
• 该账号已拥有查询或操作目标数据所需的 3CX 权限。
• 电脑已安装 WorkBuddy。
• 电脑已安装 Node.js，并可使用 npx。

3CX MCP 会继承授权用户原有的角色和权限。用户在 3CX 中无权访问的内容，通过 MCP 同样无法访问。建议遵循最小权限原则，不要为 MCP 使用共享的高权限账号。

1. 安装 Node.js

打开 Node.js 中文下载页面，下载并安装 LTS（长期支持）版本。通常保持安装程序的默认选项即可。

安装完成后，重新启动 WorkBuddy。若要确认环境是否正常，可在终端中运行：

node --version
npx --version

两条命令均能显示版本号，即表示 Node.js 和 npx 已可用。

2. 获取 3CX MCP 地址

登录 3CX 管理后台，依次进入：

Admin → Integrations → MCP Clients → Add MCP Client

创建 MCP Client 后，复制 3CX 提供的 MCP URL。其形式通常类似：

https://pbx.example.com/mcp

请保存好这个地址，后续需要将它填入 WorkBuddy 配置。

上面的域名只是示例。必须使用 3CX 管理后台为你的 PBX 生成或显示的完整 MCP URL，不要直接照抄本文或截图中的地址。

二、在 WorkBuddy 中添加 3CX MCP

1. 打开 MCP 服务管理

启动 WorkBuddy，在左侧点击 专家·技能·连接器，然后切换到顶部的 连接器。

点击右上角的 自定义连接器，打开 MCP 服务管理窗口，再点击右上角的 配置 MCP。

2. 填写 MCP 配置

在配置编辑器中填入以下内容：

{
  "mcpServers": {
    "3cx mcp": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote@latest",
        "https://pbx.example.com/mcp"
      ],
      "disabled": false
    }
  }
}

需要修改的是最后一个参数：

https://pbx.example.com/mcp

将它完整替换成你在 3CX 管理后台获得的 MCP URL，保留地址开头的 https:// 和末尾的 /mcp。

配置项说明：

配置项	作用
command	使用 Node.js 附带的 npx 启动连接程序
-y	首次运行时自动确认安装所需的 npm 包
mcp-remote@latest	将 WorkBuddy 的本地 MCP 调用连接到远程 3CX MCP 服务
MCP URL	当前 3CX PBX 的 MCP 服务地址
disabled: false	启用该 MCP 服务

填写完成后，检查 JSON 的括号、双引号和逗号是否正确，然后点击 保存。

如果配置文件中已经存在其他 MCP 服务，请只在现有的 mcpServers 对象内新增 "3cx mcp"，不要覆盖原有配置，也不要重复添加第二个 mcpServers。

三、信任并授权 3CX MCP

1. 信任 MCP 服务

保存配置后，点击 返回 MCP 列表。

首次添加的服务会显示信任确认提示。确认服务名称和 MCP 地址无误后，点击 信任。

只信任来源明确、地址已核对的 MCP 服务。MCP 工具可能读取数据或执行操作，错误或未知地址存在安全风险。

2. 完成 3CX 身份验证

信任后，点击 3CX MCP 的连接入口。WorkBuddy 会调用浏览器并进入 3CX 的验证流程：

1. 使用准备好的 3CX 用户账号登录。
2. 检查页面显示的应用和授权信息。
3. 同意授权，允许 WorkBuddy 连接 3CX MCP。
4. 授权完成后返回 WorkBuddy。

该流程采用 OAuth，不需要把 3CX 密码写入 WorkBuddy 的 mcp.json。

3. 检查连接状态

授权成功后，MCP 列表中的 3cx mcp 应显示绿色状态点，右侧开关处于开启状态，并能看到已加载的工具数量。

不同 3CX 版本、授权账号和产品许可下，可用工具数量可能不同，不必与截图中的数量完全一致。只要状态正常且可以加载工具，即可继续测试。

四、进行对话验证

关闭 MCP 服务管理窗口，在 WorkBuddy 中新建一个任务，输入：

PBX 中有多少分机？

也可以继续测试：

列出 PBX 中的分机。

查询当前活动通话。

WorkBuddy 调用 3CX MCP 后，应返回与当前账号权限相符的 PBX 数据。

建议先使用只读查询验证连接。确认返回内容正确后，再根据业务需要尝试其他工具。

五、常见问题

MCP 显示失败，或找不到 npx

• 确认已经安装 Node.js LTS。
• 在终端运行 node --version 和 npx --version。
• 安装 Node.js 后完全退出并重新打开 WorkBuddy，让应用重新读取系统环境。
• 若安装时修改过选项，请确认 Node.js 已加入系统 PATH。

保存后没有出现 3CX MCP

• 确认配置是有效的 JSON。
• 检查双引号、逗号和大括号是否成对。
• 如果原来已有 MCP 配置，应把 "3cx mcp" 合并到现有 mcpServers 中，而不是覆盖整个文件。

点击连接后没有出现授权页面

• 确认已经先点击 信任。
• 检查默认浏览器是否拦截了新窗口。
• 确认 MCP URL 来自当前 3CX 管理后台，且没有缺少 https:// 或 /mcp。
• 确认电脑可以访问该 PBX 的公网地址。

授权成功，但查询返回无权限

这是正常的权限控制结果。3CX MCP 使用当前授权账号的角色和权限，不能绕过 3CX 的访问限制。请让 3CX 管理员为该账号分配完成任务所需的最小权限，然后重新测试。

工具数量与截图不同

工具数量会受到 3CX 版本、许可、账号权限及 MCP 服务更新的影响。判断是否成功应以状态正常、工具可以加载和实际查询可用为准。

参考资料

• 3CX：Connect ChatGPT or Claude to the 3CX MCP Server
• Node.js 中文下载页面