☎️ five9-mcp

Ваш контакт-центр Five9 — в руках вашего ИИ.

Открытый MCP сервер, который подключает Claude, ChatGPT или любой MCP-клиент к облачному контакт-центру Five9 — работает на Cloudflare Workers с нулём зависимостей.

Быстрый старт · Подключить Claude · Подключить ChatGPT · Инструменты · Архитектура

Спросите свой ИИ о чём-нибудь вроде:

"Кто сейчас на звонке и насколько глубока очередь продаж?" 📊 "Создай превью-кампанию для списка возврата клиентов (win-back), привяжи навык продаж и запусти её." 🛠️ "Останови кампанию OUTBOUND_AGED и добавь этих 3 лидов в список обратных звонков." 📞 "Настрой нового агента: создай пользователя, назначь навык биллинга на уровне 2." 🧑💼 "Есть ли 555-867-5309 в нашем DNC? Проверь, прежде чем кто-то наберёт этот номер." 🚫 "Вытащи вчерашний отчёт Call Log и сведи долю брошенных вызовов." 📈 "Собери мне полный IVR: опция 1 — расписание, опция 2 — биллинг, в нерабочее время — на голосовую почту." 🧩

Под капотом этот сервер общается с Five's Configuration (admin) и Statistics (supervisor) SOAP Web Services — теми же API, на которых держится административный интерфейс Five9, — и отдаёт их в виде аккуратных JSON-инструментов через MCP streamable HTTP. Обёртки написаны вручную, XML-парсер на ~60 строк, ни одной npm-зависимости. Каждый инструмент был проверен на живом домене Five9.

✨ Встроенный веб-интерфейс

Разверните его — и ваш Worker отдаёт больше, чем просто API:

Консоль — самый быстрый способ проверить учётные данные, посмотреть, что возвращает каждый инструмент, или отладить кампанию — без участия ИИ.

Related MCP server: five9-mcp

🚀 Быстрый старт — терминал не нужен

Вам нужна бесплатная учётка Cloudflare и пользователь Five9 с доступом к API — создайте отдельного пользователя Five9 API с правами только для того, что должны делать ИИ. Не используйте личный администраторский логин.

1 — Разверните в Cloudflare (один клик, прямо в браузере)

Войдите в Cloudflare и пройдите по шагам — создастся ваша собственная копия этого Worker (а также необходимое пространство KV) и даст URL вида https://five9-mcp.you.workers.dev.

2 — Запустите мастер настройки (в браузере)

Откройте /setup на вашем новом сервере. Введите имя пользователя, пароль и регион Five9 — мастер проверит данные вживую перед сохранением и выдаст вам ключ доступа (показывается только один раз — сохраните его в менеджере паролей).

3 — Подключите свой ИИ (инструкции ниже) и попросите его "проверить подключение и показать твою кампании". 🎉

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 (секреты имеют приоритет над мастером):

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 и работают для доменов США:

🔌 Подключение ИИ

Подключение Claude (веб и десктоп)

Пользовательские коннекторы доступны на тарифах Free (один коннектор), Pro, Max, Team и Enterprise.

1. В claude.ai или в настольном приложении Claude откройте 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: владелец должен сначала добавить коннектор в 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-токен — без танцев с OAuth. Выполните /mcp внутри Claude Code, чтобы проверить.

Любой другой MCP-клиент

Всё, что говорит на MCP streamable 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, refresh-токены), рассчитанный на развёртывание с ** одним оператором**:

• «Логин» на экране согласия — это ключ доступа сервера (MCP_AUTH_TOKEN).

• Всё без состояния: идентификаторы клиентов, коды авторизации и токены — это подписанные HMAC-SHA256 навыки, завязанные на MCP_AUTH_TOKEN. Никакие KV, ни Durable Objects.

• Оба пути работают одновременно: токены OAuth и raw-ключ как bearer-credential.

• Можно отозвать всё сразу, перевыпустив секрет: npx wrangler secret put MCP_AUTH_TOKEN.

🧰 Набор инструментов

77 инструментов. 🟢 = чтение (всегда безопасно) · ✏️ = запись (изменяет ваш единство — а сервер требует от ИИ подтверждения у вас)

(69 SOAP-инструментов (username/password) + 8 REST-инструментов OAuth New Platform (Consumer Key/Secret — см. OAuth New Platform APIs).

Главная фишка: описываете звонок одним абзацем, а ИИ проектирует его, показывает Mermaid-диаграмму в чате и разворачивает рабочий IVR-скрипт. Модель не импровизирует с FourNine-XML: она заполняет ограниченную JSON-схему потока (play / menu / business-hours / skill transfer / voicemail / hangup), граф-валидатор проверяет все ветки и ссылки, а детерминированный код генерирует XML в формате дизайнера (связки модулей, кодирование промптов нижевыведения порядок полей взяты из реальных экспортированных скриптов).

Рекомендуемый пайплайн: validate → render (показать человеку!) → generate prompts → build → attached к входящей кампании. generate_prompt_audio работает на Cloudflare Workers AI по стойке: внешний TTS-аккаунт не нужен, API-ключ не нужен, доли цента за промпт списываются на ваш уже развёрнутый аккаунт Cloudflare. ElevenLabs/OpenAI тоже работают, если задать их ключи через селеты, а `{tts}......"/> (встроенный робоголос Five9) вообще не требует ничего.

Эти инструменты работают с современным REST API OAuth 2.0 New Platform от Five9, а не с SOAP API, которые используют инструменты выше. Для них необходимы учётные данные API Access (Consumer Key/Secret), а не имя пользователя и пароль SOAP — см. OAuth New Platform APIs.

🔐 OAuth New Platform APIs

Наряду с SOAP-инструментами, сервер может вызывать более новые REST API OAuth 2.0 New Platform от Five9 (например, Circles, interactions, prompts, domain metadata). Для них требуются другие учётные данные, нежели username/password для SOAP:

• API Access Control 的 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 Access Control 凭据都属于一个 系列（映射到一个 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 应该如何表现（例如 “执行写操作前先确认”）。请编辑它来描述你自己的部署方式——它默认附带了原始操作者的上下文作为示例。

🏗️ 架构

无需构建步骤，也无需外部依赖——只有位于 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 调用都会通过 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 尽管 WSDL 将其中大部分字段标记为 minOccurs="0"，仍要求提供 cleanListBeforeUpdate、crmAddMode、crmUpdateMode 和 listAddMode。

• 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 返回的信息（有名称和类型都没有）；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 构建