☎️ five9-mcp

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

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

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

Спрашивайте своего ИИ, например:

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

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

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

Разверните его — и ваш Worker будет не просто API:

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

🚀 Быстрый старт — без терминала

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

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

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

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

Откройте /setup на вашем новом сервере. Введите имя пользователя Five9, пароль и регион — мастер проверит их в реальном времени через 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 (секреты имеют приоритет над мастером):

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 откройте Настройки → Коннекторы.

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, укажите URL MCP-сервера — 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-токен — без плясок с 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).

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

• Оба пути аутентификации работают одновременно: токены, выпущенные через OAuth, и сам ключ как bearer-учётные данные.

• Отзовите всё разом, сменив секрет: npx wrangler secret put MCP_AUTH_TOKEN.

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

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

69 SOAP-инструментов (имя пользователя/пароль) + 8 REST-инструментов OAuth New Platform (Consumer Key/Secret — см. OAuth New Platform APIs).

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

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

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

🔐 OAuth New Platform APIs

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

• API Access Control Consumer Key и Consumer Secret, созданные в Five9 Admin Console → API Access Control (функция Controlled-Availability). Для создания требуется разрешение 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 family + scopes — all-apis-access не предоставляет буквально все сервисы, а права записи действуют отдельно для каждого сервиса.

Несколько наборов учётных данных / семейств. Каждый набор учётных данных API Access Control принадлежит одному семейству (сопоставленному с 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 для начала работы указан endpoint токена /v1/auth/token, но реальный endpoint — /oauth2/v1/token (именно его использует этот клиент).

🎨 Настройка контекста оператора

src/about.js содержит текст, передаваемый подключённым ИИ через поле instructions MCP и инструмент about: кто управляет сервером, зачем он существует и как ИИ должен себя вести (например, «подтверждать перед записывающими действиями»). Отредактируйте его, чтобы описать собственное развёртывание — в комплекте идёт контекст исходного оператора в качестве примера.

🏗️ Архитектура

Никакого шага сборки, никаких зависимостей — обычные 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 открывает новый SOAP-обмен с Five9 с 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>); некоторые ответы возвращают один объект там, где вы ожидали бы массив из одного элемента. toArray() в five9.js это нормализует.

• В критериях времени отчёта порядок <end> перед <start> (алфавитный порядок JAXB).

• IVR xmlDefinition — это сохраняемый формат визуального конструктора: модули связываются по GUID (ascendants / singleDescendant / branches), встроенный TTS-текст хранится в документах speakElement в виде gzip+base64, а проверки рабочих часов сравнивают системные переменные __DAY__ (SUN=1..SAT=7) и __TIME__ (минуты с полуночи). Всё это инкапсулировано в ivr.js.

• getPrompts не возвращает идентификаторы промптов (только имя + тип). Ссылки на файловые промпты внутри IVR XML принимаются с id 0 и именем промпта и нормализуются на стороне сервера; при обратном получении отправленного скрипта к нему добавляется проставленный сервером domainId.

🛡️ Безопасность

• Учётные данные Five9 хранятся только в вашем аккаунте Cloudflare — в виде секретов Worker или (вариант с мастером) в namespace Workers KV, в зашифрованном виде при хранении. Ни один инструмент никогда их не возвращает, а секреты Wrangler всегда имеют приоритет над KV.

• Мастер настройки открыт только на новом, ненастроенном сервере — запустите его сразу после развёртывания. После настройки любое изменение требует текущий ключ доступа, а серверы, управляемые через env, полностью отклоняют изменения мастера.

• Всегда завершайте настройку (или задайте MCP_AUTH_TOKEN). Ненастроенный сервер без ключа доступа работает в открытом режиме — любой, кто найдёт URL, сможет управлять вашим контакт-центром.

• Инструменты записи (✏️ выше) изменяют ваш домен. Ограничьте область действия роли пользователя Five9 API тем, что вы действительно хотите, чтобы делал ИИ, — разрешения Five9 являются настоящей границей безопасности.

• manage_dnc remove и delete_list требуют особой осторожности; инструкции about предписывают ИИ подтверждать действие перед их использованием.

• Консоль хранит ваш ключ доступа только в localStorage браузера, а вызовы идут на ваш собственный Worker с того же источника (same-origin).

💻 Разработка

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 и запускайте инструменты на вашем домене — или проведите дымовой тест из CLI с помощью приведённого выше примера curl.

🤝 Вклад в проект

PR приветствуются! Five9 Config API содержит ~180 операций, а этот сервер оборачивает 69 самых полезных — паттерн в five9.js + tools.js легко расширить (сначала прочитайте заметки о SOAP и избавьте себя от борьбы с WSDL). Пожалуйста, сохраняйте ограничение «ноль зависимостей».

📄 Лицензия

MIT · создано Ryan Shatzkamer