☎️ five9-mcp

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

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

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

Спрашивайте свой ИИ о таких вещах, как:

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

Под капотом этот сервер общается с SOAP веб-сервисами Five9 для конфигурации (администрирование) и статистики (супервизор) — теми API, которые до сих пор управляют административной панелью Five9 — и предоставляет их в виде чистых JSON-инструментов через MPC streamable HTTP. Собственноручно собранные конверты, XML-парсер примерно на 60 строк, никаких npm-пакетов. Каждый инструмент проверен на реальном домене Five9.

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

Разверните его, и ваш Worker будет обслуживать не только API:

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

Related MCP server: five9-mcp

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

Вам понадобится бесплатный аккаунт 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://<ваш-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://<ваш-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, токены обновления), предназначенный для однопользовательского развёртывания:

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

• Всё не имеет состояния — идентификаторы клиентов, коды авторизации и токены — это подписанные 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-скрипт. Модель не импровизирует с XML-кодом IVR Five9: она заполняет ограниченную JSON-спецификацию потока (воспроизведение / меню / часы работы / перевод по навыку / голосовая почта / завершение), валидатор графа проверяет каждую ветвь и ссылку, а детерминированный код генерирует XML в формате дизайнера (разводка модулей, кодировка подсказок и порядок полей — всё получено из реальных экспортированных скриптов).

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

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

🔐 OAuth API новой платформы

Наряду с SOAP-инструментами сервер может вызывать более новые REST API Новой платформы Five9 с OAuth 2.0 (например, Circles, взаимодействия, подсказки, метаданные домена). Для них используются другие учётные данные, нежели имя пользователя/пароль SOAP:

• API Access Control Consumer Key и Consumer Secret, созданные в Admin Console → API Access Control Five9 (функция с ограниченной доступностью). Для генерации требуется разрешение 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 принадлежит одному семейству (сопоставленному с продуктом API Apigee), и это семейство определяет, какие сервисы может вызывать ключ. Сервер поддерживает именованные учетные данные: 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 содержит текст, передаваемый подключенным ИИ через поле 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".

• Импорт списков/CRM является асинхронным: вызов немедленно возвращает идентификатор импорта; опрашивайте get_import_result для получения результата.

• Значения записей контактов возвращаются обернутыми (<values><data>…</data></values>); несколько ответов возвращают один объект там, где можно ожидать массив из одного элемента. toArray() в five9.js нормализует это.

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

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

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

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

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

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

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

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

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

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

💻 Разработка

npm run dev      # wrangler dev on http://localhost:8787
npm run deploy   # wrangler deploy

Поместите локальные секреты в .dev.vars (игнорируется git):

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.

🤝 Участие

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

📄 Лицензия

MIT · создано Райаном Шацкамером