☎️ five9-mcp

您的 Five9 联络中心，尽在您的 AI 手中。

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

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

您可以这样让您的 AI 做这些事：

“现在谁在通话中，销售队列深不深？” 📊 “为赢回名单创建一个预览式外呼活动，挂上销售技能，然后启动它。” 🛠️ “停止 OUTBOUND_AGED 活动，然后把这些线索加入回呼名单。” 📞 “给新坐席办理入职：创建用户，分配计费技能为 2 级。” 🧑💼 “555-867-5309 在我们的 DNC 名单上吗？有人拨打之前先检查一下。” 🚫 “拉取昨天的通话日志报告，并汇总弃呼率。” 📈 “给我搭一套完整的 IVR：按 1 转排程、按 2 转计费、非工作时间转语音信箱。” 🧩

在底层，这个服务器对接的是 Five9 的配置服务（Configuration，管理端）和统计服务（Statistics，主管端）SOAP Web Services——也就是至今仍在支撑 Five9 管理后台的 API——并通过 MCP streamable HTTP 把它们开放为简洁的 JSON 工具。手写 SOAP 信封、一个约 60 行的 XML 解析器，不依赖任何 npm 包。每个工具都在真实的 Five9 生产环境上经过了验证。

✨ 内置 Web 界面

部署完成后，你的 Worker 提供的就不只是 API 了：

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

Related MCP server: five9-mcp

🚀 快速开始——不需要终端

你需要一个免费的 Cloudflare 账号，以及一个带 API 权限的 Five9 用户——建议创建一个专用的 Five9 API 用户，把权限限制在你希望 AI 能做的范围，不要把个人管理员账号给 AI 使用。

1 — 部署到 Cloudflare（点击按钮即可，全程在浏览器）

登录 Cloudflare 后按提示点击即可——它会为你创建一份此 Worker 的副本（以及它所需的 KV 命名空间），并给你一个类似 https://five9-intercom.your.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（网页版和桌面版）

自定义连接器在 Free（限 1 个）以及 Pro、Max、Team、Enterprise 套餐中可用。

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

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

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

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

5. 在 🔐 five9-mcp 页面中，粘贴 MCP_AUTH_TOKEN 这个访问密钥，并点击 授权。

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

Team / Enterprise 的用户： owner 需要先在 组织设置 → 连接器中添加连接器；成员再在自己的设置中点击 连接 来完成授权。

连接 ChatGPT

自定义 MCP 连接器需要 开发者模式（Plus/Pro 提供该功能；Business/Enterprise 需要管理员放行自定义连接器）。

1. 在网页版 ChatGPT 中，打开 设置 → 应用与连接器（Connectors，有时只显示为 连接器）。

2. 在 高级设置 下，打开 Developer mode 开关。

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

4. 把它命名为 Five9，把 MCP 服务器地址 填为 https://<your-worker>.workers.dev/mcp，身份验证选择 OAuth。

5. 确认信任提示并保存。ChatGPT 会打开服务器的授权页——填入 MCP_AUTH_TOKEN 并点击 授权。

6. 在新对话中，打开 ＋ / 工具菜单，启用 Five9 连接器（Developer 模式下的连接器需按对话启用）。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 腾出的 token 和原始密钥做 bearer token 一样都能调用。

• 要一次性撤销所有授权，只需轮换这个 secret：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 / 营业时间 / 技能转接 / 转语音信箱 / 挂断），有一套图校验器检查每个分支和引用是否正确，再由确定性代码生成和现在一样形状的 XML（模块连线、语音提示编码、字段顺序全部取自真实导出的脚本）。

然后可以遵循：validate → render（展示给真人！）→ generate prompts → build → 接入呼入活动。generate_prompt_audio 在 Cloudflare Workers AI 上即开即用：不需要单独的 TTS 账号和 API Key，每次生成的费用不足一美分，直接记在你已经部署的 Cloudflare 账户里。如果你自己配了 Eleven程序Labs/OpenAI 的 Key，也在也行；而 {tts}（Five9 自带的机器人语音）则什么都不用配。

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

🔐 OAuth2 New Platform APIs

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

• API 访问控制中的 Consumer Key 和 Consumer Secret，在 Five9 的 Admin Console → API Access Control 中生成（该功能属受控可用性功能）。生成一个需要 security → applications → Create applications 权限，且账户必须迁移到 Five9 Identity Service（拥有旧版 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 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 sequence 校验子元素顺序。如果你要扩展这个服务器，请先拉取 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 片段在命令行做冒烟测试。

🤝 贡献

欢迎提交 PR！Five9 Config API 有大约 180 个操作，本服务器封装了其中最实用的 69 个——five9.js + tools.js 中的模式很容易扩展（先读上面的 SOAP 笔记，能省去与 WSDL 之间的艰苦拉锯）。请继续保持零依赖的约束。

📄 许可证

MIT · 由 Ryan Shatzkamer 构建。