☎️ 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 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 桌面应用中，打开 设置 → 连接器。

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 token——无需 OAuth 流程。在 Claude Code 中运行 /mcp 进行验证。

任何其他 MCP 客户端

任何支持 MCP 流式 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 签名 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 的密钥 secrets，它们也可以工作，而 {tts} 提示（Five9 内置的机器人语音）则完全不需要任何东西。

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

🔐 OAuth New Platform APIs

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

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

• 将它们配置为环境变量/密钥变量（与 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 工具会自动使用 data-tables 凭据；rest_call 和 rest_check_connection 接受一个 credential 参数来选择使用哪个。

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

🎨 自定义操作员上下文

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

🏗️ 架构

无需构建步骤，无依赖 — 纯 JS 模块，位于 src/ 中：

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 Basic 认证发起一次全新的 Five9 SOAP 交换。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"。

• 列表/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 Config API 有约 180 个操作，此服务器封装了其中 69 个最常用的操作 — five9.js + tools.js 中的模式易于扩展（请先阅读 SOAP 说明，以免与 WSDL 纠缠不清）。请保持零依赖的约束。

📄 许可证

MIT · 由 Ryan Shatzkamer 构建