☎️ 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 Configuration (администрирование) и Statistics (супервизор) — API, которые до сих пор управляют административной поверхностью Five9, — и предоставляет их как чистые JSON-инструменты через MCP 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://<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).

• Всё не имеет состояния — идентификаторы клиентов, коды авторизации и токены — это подписанные 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-спецификацию потока (play / menu / business-hours / skill transfer / voicemail / hangup), валидатор графа проверяет каждую ветвь и ссылку, а детерминированный код генерирует XML в форме дизайнера (соединение модулей, кодирование подсказок и порядок полей — всё получено из реальных экспортированных скриптов).

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

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

• Ключ доступа (Consumer Key) и секретный ключ (Consumer Secret) API Access Control, созданные в 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__ (SUN=1..SAT=7) и __TIME__ (минуты с полуночи). ivr.js инкапсулирует все это.

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

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

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

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

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

• Инструменты записи (✏️ выше) изменяют ваш домен. Ограничьте роль API-пользователя Five9 только тем, что вы действительно хотите позволить ИИ делать — разрешения 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 (файл исключен из 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 и выполняйте инструменты против вашего домена — или проверяйте из командной строки с помощью приведенного выше фрагмента curl.

🤝 Вклад

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

📄 Лицензия

MIT · автор — Ryan Shatzkamer