Skip to main content
Glama

☎️ five9-mcp

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

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

License: MIT Runtime Dependencies MCP Tools

快速开始 · 连接 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 连接教程,以及完整的工具目录

/setup

设置向导——在浏览器中输入 Five9 凭据,实时完成验证,然后获取您的访问密钥。无需终端,无需 secrets 命令

/console

交互式控制台——粘贴您的访问密钥,从 77 个分组工具中任选一个,填写按工具 schema 自动生成的表单,直接在浏览器中针对您的实时 Five9 域运行

/mcp

MCP 端点本身(streamable HTTP,无状态)

/health

JSON 健康检查

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

Related MCP server: five9-mcp

🚀 快速开始——无需终端

您需要一个免费的 Cloudflare 账户,以及一个具有 API 访问权限的 Five9 用户——创建一个专用的 Five9 API 用户,将其权限限定为您希望 AI 执行的操作,切勿复用个人管理员登录账号。

1 — 部署到 Cloudflare (在浏览器中一键完成)

Deploy to 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 中,适用于美国区域:

变量

默认值

说明

FIVE9_API_HOST

api.five9.com

欧盟:api.eu.five9.com · 加拿大:api.ca.five9.com

FIVE9_ADMIN_VERSION

v13

Config Web Services WSDL 版本

FIVE9_SUPERVISOR_VERSION

v13

Statistics Web Services WSDL 版本

🔌 连接您的 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_ivr_flow

对流程规范进行图形校验,并验证所引用的技能/提示语在域上存在

🟢

render_ivr_flow

将流程规范或现有 IVR 脚本渲染为 Mermaid 流程图

✏️

build_ivr_script

组合出完整的脚本 XML,并在域上创建它(可先使用 dry_run 进行检查)

✏️

generate_prompt_audio

用现代 AI 语音为提示语配音,并上传为 Five9 可直接使用的 G.711 u-law WAV。无需 API 密钥:由 Worker 内置的 Workers AI(Deepgram Aura,约 40 种语音)提供支持

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

工具

功能说明

🟢

about

供 AI 使用的运营者上下文——谁在运行此服务器,以及基本规则

🟢

check_connection

验证 Five9 凭据是否有效;返回可见的技能数量

🟢

get_api_usage

当前 Five9 API 使用量计数器与速率限制的对比

工具

功能说明

🟢

list_campaigns

列出活动(名称、类型、状态、模式)

🟢

inspect_campaign

一次调用获取状态 + 关联列表 + DNIS

🟢

get_campaign_details

完整活动配置(拨号模式、比率、录音、后处理…)

✏️

create_campaign

创建呼出或呼入活动,BASIC 或 ADVANCED

✏️

modify_campaign

编辑任意活动设置 — 读-改-写,只传递更改项

✏️

rename_campaign

重命名活动

✏️

delete_campaign

删除活动

✏️

control_campaign

启动 / 停止 / force_stop / 重置 / 重置列表位置

✏️

manage_campaign_lists

按优先级附加/分离拨号列表

✏️

manage_campaign_skills

在活动上添加/移除路由技能

✏️

manage_campaign_dnis

附加/分离呼入号码

✏️

manage_campaign_dispositions

在活动上添加/移除座席处理码

🟢

list_campaign_profiles

列出活动配置文件(ANI、尝试次数、超时时间)

✏️

manage_campaign_profile

创建 / 修改 / 删除活动配置文件

✏️

manage_campaign_profile_filter

读取 / 编辑配置文件的 CRM 记录选择条件和拨号顺序

工具

功能说明

🟢

list_dialing_lists

列出拨号列表 + 记录数

✏️

create_list / delete_list

创建或删除拨号列表

✏️

add_record_to_list

将线索推入列表(异步导入)

✏️

add_records_to_list

在一次异步导入中批量添加大量线索(可配置 CRM/列表模式)

✏️

delete_record_from_list

从列表中移除匹配的记录

🟢

get_import_result

异步列表/CRM 导入的结果

工具

功能说明

🟢

search_contacts

按精确字段值查找联系人

✏️

update_contact

更新联系人(默认仅匹配唯一记录时更新)

✏️

bulk_update_contacts

在一次异步导入中批量更新多个 CRM 联系人(使用类型 "crm" 轮询)

✏️

delete_contact

删除联系人(仅在恰好匹配一条时删除)

🟢

list_contact_fields

域的联系人字段架构

✏️

manage_contact_field

创建 / 修改 / 删除自定义 CRM 字段

工具

功能说明

✏️

manage_dnc

检查 / 添加 / 移除域 DNC 列表中的号码

🟢

get_dialing_rules

域拨号规则(时间/州限制)

工具

功能说明

🟢

list_users

列出用户及常规信息

🟢

get_user_details

单个用户的完整记录:角色、技能、组

✏️

create_user

创建用户并设置角色、技能和组

✏️

modify_user

编辑用户信息 — 只传递更改项

✏️

delete_user

删除用户

🟢

list_user_profiles

角色/权限模板

🟢

list_skills / get_skill_details

技能(可包含或不包含已分配用户)

✏️

manage_skill

创建 / 修改 / 删除技能

✏️

manage_user_skills

为用户分配技能并设置级别

✏️

set_user_roles

授予 / 撤销角色(agent、admin、supervisor、reporting、crmManager)及权限标签页

🟢

list_agent_groups

座席组 + 成员

✏️

manage_agent_group

创建 / 删除组,添加/移除座席

✏️

manage_reason_code

未就绪 / 注销原因代码

工具

功能说明

🟢

list_dispositions

通话处理码及其设置

✏️

manage_disposition

创建 / 修改 / 重命名 / 删除处理码(包括重拨定时器)

🟢

list_ivr_scripts / get_ivr_script

IVR 脚本 — 元数据,或某个脚本的完整 XML

✏️

manage_ivr_script

创建 / 修改 / 删除 IVR 脚本(推送完整的 xmlDefinition)

🟢

list_prompts

域上的语音提示

✏️

manage_tts_prompt

创建 / 修改 / 删除文本转语音提示

✏️

manage_wav_prompt

创建 / 修改 / 删除预录的 WAV 提示(base64;G.711 µ-law 8kHz 单声道)

🟢

list_dnis

已配置的呼入号码(可选仅未分配)

🟢

list_call_variables

通话变量和变量组

✏️

manage_call_variable

创建 / 删除自定义通话变量

🟢

list_web_connectors

Web 连接器集成

✏️

manage_web_connector

创建 / 删除 Web 连接器(座席触发时弹出 URL)

✏️

manage_speed_dial

列出 / 创建 / 删除快速拨号代码

🟢

get_vcc_configuration

域级 VCC 设置

工具

功能说明

🟢

run_report

按文件夹 + 名称启动任意报表,可选时间范围

🟢

get_report_result

轮询获取报表的 CSV 输出

🟢

get_realtime_stats

AgentState、ACDStatus、CampaignState、活动统计(包括拨号器管理器与自动拨号视图)

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

工具

功能说明

🟢

rest_check_connection

验证 OAuth 凭据 — 获取 bearer 令牌(不访问域数据)

🟢✏️

rest_call

对任意 New Platform 端点的通用已认证调用(方法 + 路径 + 请求体),支持速率限制/退避和 ETag

🟢✏️

manage_circle

Circles — 列出 / 获取 / 创建 / 删除(无 SOAP 对应)

🟢

list_np_prompts

通过 New Platform prompts API 获取语音提示(分页)

🟢

list_interaction_dispositions

通过 interactions API 获取处理码(比 SOAP 列表更丰富;只读)

🟢

get_domain_info

域元数据(id、名称、租户、服务端点)

🟢

list_data_tables

Data Tables(结构化查找表;无 SOAP 对应)— 使用单独的 data-tables 凭据

🟢

get_data_table_rows

按 id 获取 Data Table 的行(分页)

🔐 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 构建

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      Not graded
      maintenance
      Connects AI assistants to Five9 cloud contact center, enabling management of campaigns, agents, call logs, and more through natural language commands.
      MIT
    • A
      license
      Not graded
      quality
      Not graded
      maintenance
      Connects AI assistants to the Five9 cloud contact center, enabling them to manage campaigns, agents, IVR flows, and monitor call statistics through a secure, zero-dependency MCP server.
      MIT
    • A
      license
      Not graded
      quality
      Not graded
      maintenance
      Enables AI assistants to operate a Five9 contact center—managing campaigns, agents, IVR flows, call statistics, and compliance lists—through natural language via Five9's SOAP and REST APIs.
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables AI assistants to manage and monitor a Five9 contact center, including campaigns, agents, IVR flows, call statistics, and reports through MCP.
      MIT