☎️ five9-mcp

让您的 Five9 联络中心尽在 AI 的掌控之中。

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

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

您可以向 AI 提出这样的问题：

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

在底层，该服务器对接 Five9 的 Configuration（管理）与 Statistics（主管）SOAP Web Services——也就是仍在驱动 Five9 管理界面的那套 API——并通过 MCP streamable HTTP 将它们以简洁的 JSON 工具形式暴露出来。手工编写的 SOAP 信封、一个约 60 行的 XML 解析器，没有 npm 包。每一个工具都已在真实的 Five9 域上进行过实战验证。

✨ 内置 Web UI

部署之后，您的 Worker 所提供的远不止是一个 API：

控制台是验证凭据、查看每个工具返回内容或调试活动的最快方式——完全不需要 AI。

🚀 快速开始——无需终端

您需要一个免费的 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 secrets 来管理凭据（secrets 会覆盖向导）：

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 Desktop 应用中，打开 Settings → Connectors。

2. 点击 Add custom connector。

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

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

5. 在 🔐 five9-mcp 界面中，将您的 MCP_AUTH_TOKEN 作为访问密钥粘贴进去，然后点击 Authorize。

6. 在任意聊天中，打开 search & tools（＋）菜单，确保 Five9 连接器已开启。

**Team/Enterprise：**Owner 先在 Organization settings → Connectors 下添加连接器；成员随后在自己的设置中点击 Connect 以完成授权。

连接 ChatGPT

自定义 MCP 连接器需要 Developer mode（Plus/Pro 计划；Business/Enterprise 计划下需要管理员允许使用自定义连接器）。

1. 在 ChatGPT 网页版中，打开 Settings → Apps & Connectors（有时仅标记为 Connectors）。

2. 在 Advanced settings 下，开启 Developer mode。

3. 返回 Connectors 页面，点击 Create。

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

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

6. 在新聊天中，打开 ＋ / 工具菜单并启用 Five9 连接器（Developer mode 下的连接器按会话启用）。ChatGPT 会要求您确认每一次工具调用——对于任何可能启动拨号器的操作来说，这都很合理。😄

连接 Claude Code

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

原始访问密钥可直接作为 bearer token 使用——无需繁琐的 OAuth 授权流程。在 Claude Code 中运行 /mcp 即可验证。

其他 MCP 客户端

任何支持 MCP streamable HTTP 的客户端均可使用——完成 OAuth 流程，或将访问密钥作为 bearer token 发送：

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 签名数据块。无需 KV，也无需 Durable Objects。

• 两条认证路径可同时工作：OAuth 签发的令牌以及作为 bearer 凭据的原始密钥。

• 轮换密钥即可一次性撤销所有凭据：npx wrangler secret put MCP_AUTH_TOKEN。

🧰 工具箱

77 个工具。 🟢 = 读取（始终安全）· ✏️ = 写入（会更改您的域——服务器会提示 AI 先征得您的确认）

69 个 SOAP 工具（用户名/密码）+ 8 个 OAuth New Platform REST 工具（Consumer Key/Secret——参见 OAuth New Platform APIs）。

核心亮点：用一段话描述呼叫流程，AI 就会设计出来，在聊天中向您展示 Mermaid 流程图，并部署一个可正常运行的 IVR 脚本。模型绝不会自行发挥编造 Five9 的 IVR XML：它会填写一个受约束的 JSON 流程规范（play / menu / business-hours / skill transfer / voicemail / hangup），图形校验器会检查每一个分支和引用，确定性的代码则会生成设计器形态的 XML（模块连线、提示语编码和字段顺序均源自真实导出的脚本）。

推荐流程：validate → render（先展示给用户看！）→ generate prompts → build → 挂接到呼入活动。generate_prompt_audio 开箱即用，运行在 Cloudflare Workers AI 之上：无需外部 TTS 账户，无需 API 密钥，每条提示语仅需几分之一美分，费用直接计入您完成部署所用的 Cloudflare 账户。只要设置了相应的密钥 secrets，ElevenLabs/OpenAI 同样可以工作；而 {tts} 提示语（Five9 内置的机器人语音）则完全不需要任何配置。

这些工具使用的是 Five9 现代的 OAuth 2.0 "New Platform" REST APIs，而非上述工具使用的 SOAP APIs。它们需要 API Access Control 凭据（Consumer Key/Secret），不是 SOAP 用户名/密码 — 参见 OAuth New Platform APIs。

🔐 OAuth New Platform APIs

除了 SOAP 工具之外，服务器还可以调用 Five9 较新的 OAuth 2.0 "New Platform" REST APIs（例如 Circles、interactions、prompts、域元数据）。这些 API 使用的凭据与 SOAP 用户名/密码不同：

• 一个 API Access Control 的 Consumer Key 和 Consumer Secret，在 Five9 Admin Console → API Access Control（一项受控可用性功能）中生成。生成一个需要 security → applications → Create applications 权限，并且账户必须迁移到 Five9 Identity Service（具有旧版 API/Agent/Supervisor 角色的用户在这些角色被移除之前不会参与迁移）。

• 将它们配置为 env/secret 变量（均与 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 Product），该系列决定该密钥可以调用哪些服务。服务器支持命名凭据：default（来自 FIVE9_CONSUMER_KEY/SECRET）以及 data-tables（来自 FIVE9_DT_CONSUMER_KEY/SECRET）。Data Tables 工具会自动使用 data-tables 凭据；rest_call 和 rest_check_connection 接受一个 credential 参数来选择凭据。

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

🎨 自定义操作者上下文

src/about.js 保存着通过 MCP instructions 字段和 about 工具提供给已连接 AI 的文本：谁在操作服务器、它为什么存在，以及 AI 应如何表现（例如 “在执行写入操作前确认”）。请编辑它来描述你自己的部署——它随附了原操作者的上下文作为示例。

🏗️ 架构

无需构建步骤、无依赖——src/ 中的纯 JS 模块：

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 调用都会发起一次全新的 Five9 SOAP 交换，并使用 HTTP Basic 认证。Statistics API 还需要一次 setSessionParameters 调用，get_realtime_stats 会在每次调用时执行它。

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

• addToListCsv 要求提供 cleanListBeforeUpdate、crmAddMode、crmUpdateMode 和 listAddMode，尽管 WSDL 将其中大部分标记为 minOccurs="0"。

• List/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 secrets，或（向导方式）存放在 Workers KV 命名空间中，并静态加密。没有任何工具会返回它们，并且 Wrangler secrets 始终覆盖 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

将本地 secret 放入 .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 Config API 有 ~180 个操作，此服务器封装了其中 69 个最常用的操作——five9.js + tools.js 中的模式很容易扩展（先阅读 SOAP 说明，省得与 WSDL 较劲）。请保持零依赖约束。

📄 许可证

MIT · 由 Ryan Shatzkamer 构建