☎️ five9-mcp

你的 Five9 联络中心，尽在 AI 掌控之中。

一个开源的 MCP 服务器，将 Claude、ChatGPT 或任何 MCP 客户端连接到 Five9 云联络中心——运行在 Cloudflare Workers 上，零依赖。

快速开始 · 连接 Claude · 连接 ChatGPT · 工具 · 架构

向你的 AI 提问，例如：

“现在谁在通话中？销售队列有多深？” 📊 “为赢回名单创建一个预览式外呼活动，关联销售技能，然后启动它。” 🛠️ “停止 OUTBOUND_AGED 活动，并将这 3 个线索添加到回呼列表。” 📞 “入职新坐席：创建用户，分配计费技能，级别为 2。” 🧑💼 “555-867-5309 在我们的 DNC 名单上吗？在任何人拨打之前检查一下。” 🚫 “拉取昨天的通话记录报告，并总结放弃率。” 📈 “为我构建一个完整的 IVR：选项 1 排班，选项 2 计费，非工作时间转语音信箱。” 🧩

在底层，此服务器与 Five9 的配置（管理）和统计（主管）SOAP Web 服务通信——这些 API 仍然驱动着 Five9 的管理界面——并通过 MCP 流式 HTTP 将它们暴露为干净的 JSON 工具。手工制作的信封，约 60 行的 XML 解析器，无 npm 包。每个工具都已在真实的 Five9 域上测试过。

✨ 内置 Web UI

部署后，你的 Worker 提供的不仅仅是 API：

控制台是快速验证凭据、探索每个工具返回内容或调试活动的最快方式——无需 AI。

Related MCP server: five9-mcp

🚀 快速开始——无需终端

你需要一个免费的 Cloudflare 账户和一个具有 API 访问权限的 Five9 用户——创建一个专用的 Five9 API 用户，权限范围限定为你希望 AI 执行的操作，不要重复使用个人管理员登录。

1 — 部署到 Cloudflare （一键，在浏览器中）

登录 Cloudflare 并点击通过——它会创建你自己的 Worker 副本（以及所需的 KV 命名空间），并为你提供一个类似 https://five9-mcp.you.workers.dev 的 URL。

2 — 运行设置向导 （在浏览器中）

在新服务器的 /setup 页面打开。输入你的 Five9 用户名、密码和区域——向导在保存前实时向 Five9 验证它们，然后提供你的访问密钥（仅显示一次——请存储在密码管理器中）。

3 — 连接你的 AI（下方有教程），然后让它 “检查连接并列出我的活动。” 🎉

git clone https://github.com/ryanshatz/five9-mcp
cd five9-mcp
npx wrangler deploy   # provisions the CONFIG KV namespace on first deploy

然后，你可以使用 /setup 向导，或者跳过它，将凭据作为 Wrangler 密钥管理（密钥会覆盖向导设置）：

npx wrangler secret put FIVE9_USERNAME   # e.g. apiuser@yourdomain
npx wrangler secret put FIVE9_PASSWORD
npx wrangler secret put MCP_AUTH_TOKEN   # a long random string — this is the key to your server

默认值位于 wrangler.toml 中，适用于美国域：

🔌 连接你的 AI

连接 Claude（Web 和桌面）

自定义连接器适用于 Free（一个连接器）、Pro、Max、Team 和 Enterprise 计划。

1. 在 claude.ai 或 Claude 桌面应用中，打开 设置 → 连接器。

2. 点击 添加自定义连接器。

3. 命名为 Five9，并粘贴你的服务器 URL，包括 /mcp 路径： https://<your-worker>.workers.dev/mcp

4. 点击 添加，然后 连接。Claude 会自动发现此服务器的内置 OAuth 并打开其授权页面。

5. 在 🔐 five9-mcp 屏幕上，将你的 MCP_AUTH_TOKEN 作为访问密钥粘贴，然后点击 授权。

6. 在任何聊天中，打开 搜索和工具（＋）菜单，确保 Five9 连接器已开启。

Team/Enterprise： 所有者首先在 组织设置 → 连接器 下添加连接器；然后成员在自己的设置中点击 连接 进行授权。

连接 ChatGPT

自定义 MCP 连接器需要 开发者模式（Plus/Pro；在 Business/Enterprise 上，管理员必须允许自定义连接器）。

1. 在 ChatGPT 网页版中，打开 设置 → 应用和连接器（有时仅标为 连接器）。

2. 在 高级设置 下，开启 开发者模式。

3. 返回连接器页面，点击 创建。

4. 命名为 Five9，将 MCP 服务器 URL 设置为 https://<your-worker>.workers.dev/mcp，并选择 OAuth 认证。

5. 确认信任提示并保存。ChatGPT 会打开此服务器的授权页面——粘贴你的 MCP_AUTH_TOKEN 并点击 授权。

6. 在新聊天中，打开 ＋ / 工具菜单，启用 Five9 连接器（开发者模式连接器按对话启用）。ChatGPT 会要求你确认每个工具调用——对于任何可能启动拨号器的操作来说，这是明智的。😄

连接 Claude Code

claude mcp add --transport http five9 https://<your-worker>.workers.dev/mcp \
  --header "Authorization: Bearer <your MCP_AUTH_TOKEN>"

原始访问密钥可直接作为 Bearer 令牌使用——无需 OAuth 流程。在 Claude Code 中运行 /mcp 进行验证。

任何其他 MCP 客户端

任何支持 MCP 流式 HTTP 的客户端都可以——完成 OAuth 流程或将访问密钥作为 Bearer 令牌发送：

curl -X POST https://<your-worker>.workers.dev/mcp \
  -H "Authorization: Bearer <MCP_AUTH_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"check_connection","arguments":{}}}'

src/oauth.js 实现了一个极简的 OAuth 2.1 授权服务器（元数据发现、动态客户端注册、PKCE S256、刷新令牌），专为单操作员部署设计：

• 同意屏幕上的“登录”是服务器的访问密钥（MCP_AUTH_TOKEN）。

• 一切都是无状态的——客户端 ID、授权码和令牌都是使用 MCP_AUTH_TOKEN 作为密钥的 HMAC-SHA256 签名 blob。无需 KV，无需 Durable Objects。

• 两种认证路径同时工作：OAuth 颁发的令牌和原始密钥作为 Bearer 凭据。

• 通过轮换密钥一次性撤销所有内容：npx wrangler secret put MCP_AUTH_TOKEN。

🧰 工具包

77 个工具。 🟢 = 读取（始终安全）· ✏️ = 写入（会更改你的域——服务器会告知 AI 先与你确认）

69 个 SOAP 工具（用户名/密码）+ 8 个 OAuth 新平台 REST 工具（消费者密钥/秘密——请参阅 OAuth 新平台 API）。

核心技巧：用一段话描述通话流程，AI 会设计它，在聊天中向你展示Mermaid 图表，并部署一个可运行的 IVR 脚本。模型不会随意生成 Five9 的 IVR XML：它会填充一个受限的 JSON 流程规范（播放/菜单/营业时间/技能转接/语音信箱/挂断），图形验证器会检查每个分支和引用，确定性代码会生成设计器风格的 XML（模块接线、提示编码和字段顺序均来自真实导出的脚本）。

推荐流程：验证 → 渲染（展示给用户！） → 生成提示 → 构建 → 关联到入站活动。generate_prompt_audio 开箱即用，运行在 Cloudflare Workers AI 上：无需外部 TTS 账户，无需 API 密钥，每个提示仅需几分钱，计入你已经部署的 Cloudflare 账户。如果设置了密钥，ElevenLabs/OpenAI 也可用，而 {tts} 提示（Five9 内置的机器人语音）则完全不需要任何东西。

这些工具调用 Five9 的现代 OAuth 2.0 "新平台" REST API，而非上述工具使用的 SOAP API。它们需要 API 访问控制凭证（Consumer Key/Secret），而非 SOAP 用户名/密码 — 请参阅 OAuth 新平台 API。

🔐 OAuth 新平台 API

除了 SOAP 工具外，服务器还可以调用 Five9 较新的 OAuth 2.0 新平台 REST API（例如圈子、交互、提示、域元数据）。这些使用与 SOAP 用户名/密码不同的凭证：

• API 访问控制的 消费者密钥 和 消费者密钥密文，在 Five9 管理控制台 → API 访问控制中生成（这是一个受限可用功能）。生成密钥需要 security → applications → Create applications 权限，并且账户必须迁移到 Five9 身份服务（拥有旧版 API/代理/主管角色的用户在移除这些角色之前无法迁移）。

• 将它们配置为环境变量/密钥变量（全部与 SOAP 凭据分开）：

FIVE9_CONSUMER_KEY=...           # "All APIs access" family credential (default)
FIVE9_CONSUMER_SECRET=...
FIVE9_DOMAIN_ID=131109           # your Admin Console domain id
FIVE9_REST_REGION=US             # US | US-ALPHA | CA | EU | IN | UK
# or pin the base URL directly: FIVE9_REST_BASE_URL=https://api.prod.us.five9.net

# Optional second credential for the "Data Tables access" family (its own key):
FIVE9_DT_CONSUMER_KEY=...
FIVE9_DT_CONSUMER_SECRET=...

然后运行 rest_check_connection 以确认令牌流程。每个凭据可以访问的内容由其 API 系列 + 作用域 决定 — all-apis-access 并不真正授予所有服务，写入权限是按服务划分的。

多个凭据/系列。 每个 API 访问控制凭据属于一个系列（映射到一个 Apigee API 产品），该系列决定了密钥可以调用哪些服务。服务器支持命名凭据：default（来自 FIVE9_CONSUMER_KEY/SECRET）和 data-tables（来自 FIVE9_DT_CONSUMER_KEY/SECRET）。数据表工具自动使用 data-tables 凭据；rest_call 和 rest_check_connection 接受一个 credential 参数来选择凭据。

注意： Five9 的入门文档将令牌端点列为 /v1/auth/token，但实际端点是 /oauth2/v1/token（此客户端使用的端点）。

🎨 自定义操作员上下文

src/about.js 保存了通过 MCP instructions 字段和 about 工具提供给已连接 AI 的文本：谁在运行服务器，它存在的原因，以及 AI 应如何表现（例如，"在写入操作前确认"）。编辑它以描述您自己的部署 — 它附带原始操作员的上下文作为示例。

🏗️ 架构

无需构建步骤，无依赖项 — src/ 中的纯 JavaScript 模块：

src/
├── index.js   # router, CORS, MCP JSON-RPC handler, /setup endpoint
├── five9.js   # SOAP client: envelope builder, ~60-line XML parser, one method per Five9 op
├── tools.js   # MCP tool definitions (JSON Schema) + dispatch
├── oauth.js   # stateless OAuth 2.1 server (single-operator model)
├── config.js  # config resolution: Wrangler secrets > KV (setup wizard)
├── ui.js      # landing page, setup wizard, interactive console
└── about.js   # operator context — edit this for your deployment

请求是无状态的：每个 MCP 调用都会使用 HTTP 基本认证打开一个新的 Five9 SOAP 交换。统计 API 额外需要 setSessionParameters 调用，get_realtime_stats 每次调用都会执行此操作。

• Five9 的端点由 JAXB 生成，并根据 WSDL 序列验证子元素顺序。如果您扩展此服务器，请拉取 WSDL（https://api.five9.com/wsadmin/v13/AdminWebService?wsdl，HTTP 基本认证）并精确匹配 <xs:sequence> 顺序 — 包括像 basicImportSettings 这样的基类型，其元素位于扩展的元素之前。

• addToListCsv 需要 cleanListBeforeUpdate、crmAddMode、crmUpdateMode 和 listAddMode，即使 WSDL 将其中大部分标记为 minOccurs="0"。

• 列表/CRM 导入是异步的：调用立即返回一个导入标识符；轮询 get_import_result 以获取结果。

• 联系人记录值以包装形式返回（<values><data>…</data></values>）；多个响应在您期望单元素数组的地方返回单个对象。five9.js 中的 toArray() 对此进行了规范化。

• 报告时间条件顺序是 <end> 在 <start> 之前（JAXB 按字母顺序排序）。

• IVR xmlDefinition 是可视化设计器的持久化格式：模块通过 GUID（ascendants / singleDescendant / branches）连接，内联 TTS 文本存储为 gzip+base64 编码的 speakElement 文档，营业时间检查比较 __DAY__（SUN=1..SAT=7）和 __TIME__（自午夜以来的分钟数）系统变量。ivr.js 封装了所有这些。

• getPrompts 返回无提示 ID（仅名称 + 类型）。IVR XML 中的文件提示引用接受 id 0 + 提示名称，并在服务器端进行规范化；推送的脚本会与服务器标记的 domainId 一起往返。

🛡️ 安全性

• Five9 凭据仅存在于您的 Cloudflare 账户中 — 作为 Worker 密钥，或（向导路径）存储在 Workers KV 命名空间中，静态加密。没有工具会返回它们，并且 Wrangler 密钥始终覆盖 KV。

• 设置向导仅在全新、未配置的服务器上开放 — 部署后立即运行。配置后，任何更改都需要当前访问密钥，并且环境管理的服务器完全拒绝向导更改。

• 始终完成设置（或设置 MCP_AUTH_TOKEN）。 未配置且没有访问密钥的服务器是开放的 — 任何找到 URL 的人都可以操控您的联络中心。

• 写入工具（上面的 ✏️）会更改您的域。将 Five9 API 用户的角色范围限定为您实际希望 AI 执行的操作 — Five9 权限是真正的安全边界。

• manage_dnc remove 和 delete_list 需要格外小心；about 指令告诉 AI 在使用它们之前进行确认。

• 控制台仅将您的访问密钥存储在浏览器的 localStorage 中，并且调用是同源的，指向您自己的 Worker。

💻 开发

npm run dev      # wrangler dev on http://localhost:8787
npm run deploy   # wrangler deploy

将本地密钥放在 .dev.vars 中（已加入 gitignore）：

FIVE9_USERNAME=apiuser@yourdomain
FIVE9_PASSWORD=...
MCP_AUTH_TOKEN=dev-local-token

# Optional — external AI voice providers for generate_prompt_audio.
# The default (Workers AI / Deepgram Aura) needs no key at all.
ELEVENLABS_API_KEY=...
OPENAI_API_KEY=...

# Optional — OAuth New Platform REST tools (separate credential; see below)
FIVE9_CONSUMER_KEY=...
FIVE9_CONSUMER_SECRET=...
FIVE9_DOMAIN_ID=131109
FIVE9_REST_REGION=US
FIVE9_DT_CONSUMER_KEY=...        # optional: "Data Tables access" family
FIVE9_DT_CONSUMER_SECRET=...

然后打开 http://localhost:8787/console，粘贴 dev-local-token，并针对您的域运行工具 — 或使用上面的 curl 片段从 CLI 进行冒烟测试。

🤝 贡献

欢迎提交 PR！Five9 配置 API 有约 180 个操作，此服务器封装了其中最有用的 69 个 — five9.js + tools.js 中的模式易于扩展（先阅读 SOAP 注意事项，以免与 WSDL 纠缠不清）。请保持零依赖的约束。

📄 许可证

MIT · 由 Ryan Shatzkamer 构建