☎️ five9-mcp

Ihr Five9-Kontaktcenter in den Händen Ihrer KI.

Ein Open-Source-MCP-Server, der Claude, ChatGPT oder einen beliebigen MCP-Client mit dem Five9-Cloud-Kontaktcenter verbindet — betrieben auf Cloudflare Workers mit null Abhängigkeiten.

Schnellstart · Claude verbinden · ChatGPT verbinden · Toolbox · Architektur

Fragen Sie Ihre KI zum Beispiel:

„Wer ist gerade in einem Anruf und wie tief ist die Vertriebswarteschlange?“ 📊 „Erstelle eine Preview-Kampagne für die Rückhol-Liste, weise die Vertriebsfähigkeit zu und starte sie.“ 🛠️ „Stoppe die OUTBOUND_AGED-Kampagne und füge diese 3 Leads zur Rückrufliste hinzu.“ 📞 „Binde den neuen Agenten ein: Lege den Benutzer an, weise die Abrechnungsfähigkeit auf Stufe 2 zu.“ 🧑💼 „Steht 555-867-5309 auf unserer DNC-Liste? Prüfe, bevor jemand sie wählt.“ 🚫 „Hole den Anrufprotokollbericht von gestern und fasse die Abbrecherquoten zusammen.“ 📈 „Baue mir eine komplette IVR: Option 1 Terminplanung, Option 2 Abrechnung, außerhalb der Geschäftszeiten geht es zur Voicemail.“ 🧩

Unter der Haube spricht dieser Server die SOAP-Webdienste für Five9-Konfiguration (Admin) und Statistik (Supervisor) — die APIs, die weiterhin die Five9-Admin-Oberfläche betreiben — und stellt sie als saubere JSON-Tools über MCP streamable HTTP bereit. Handgebaute Envelopes, ein ~60-zeiliger XML-Parser, keine npm-Pakete. Jedes Tool wurde gegen eine echte Five9-Domäne getestet.

✨ Integrierte Web-Oberfläche

Die Konsole ist der schnellste Weg, um Zugangsdaten zu überprüfen, zu erkunden, was jedes Tool zurückgibt, oder eine Kampagne zu debuggen — ganz ohne KI.

🚀 Schnellstart — ganz ohne Terminal

Sie brauchen ein kostenloses Cloudflare-Konto und einen Five9-Benutzer mit API-Zugriff — legen Sie einen dedizierten Five9-API-Benutzer an, der auf das beschränkt ist, was eine KI tun soll, und verwenden Sie keinen persönlichen Admin-Login wieder.

1 — Auf Cloudflare bereitstellen (ein Klick, im Browser)

Melden Sie sich bei Cloudflare an und klicken Sie sich durch — es erstellt eine eigene Kopie dieses Workers (plus den benötigten KV-Namespace) und gibt Ihnen eine URL wie https://five9-mcp.you.workers.dev.

2 — Setup-Assistent ausführen (im Browser)

Öffnen Sie auf Ihrem neuen Server /setup. Geben Sie Ihren Five9-Benutzernamen, Ihr Passwort und Ihre Region ein — der Assistent verifiziert sie live gegen Five9, bevor er speichert, und übergibt Ihnen dann Ihren Zugriffsschlüssel (wird nur einmal angezeigt — bewahren Sie ihn in einem Passwort-Manager auf).

3 — Verbinden Sie Ihre KI (Anleitungen unten) und bitten Sie sie dann: „Prüfe die Verbindung und liste meine Kampagnen auf.“ 🎉

git clone https://github.com/ryanshatz/five9-mcp
cd five9-mcp
npx wrangler deploy   # provisions the CONFIG KV namespace on first deploy

Dann nutzen Sie entweder den /setup-Assistenten oder überspringen Sie ihn und verwalten Sie Zugangsdaten als Wrangler-Secrets (Secrets überschreiben den Assistenten):

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

Die Standardwerte stehen in wrangler.toml und gelten für US-Domänen:

🔌 Verbinden Sie Ihre KI

Claude verbinden (Web & Desktop)

Benutzerdefinierte Connectors sind in den Plänen Free (ein Connector), Pro, Max, Team und Enterprise verfügbar.

1. Öffnen Sie in claude.ai oder in der Claude-Desktop-App Einstellungen → Connectors.

2. Klicken Sie auf Benutzerdefinierten Connector hinzufügen.

3. Nennen Sie ihn Five9 und fügen Sie Ihre Server-URL einschließlich des /mcp-Pfads ein: https://<your-worker>.workers.dev/mcp

4. Klicken Sie auf Hinzufügen und dann auf Verbinden. Claude erkennt das integrierte OAuth dieses Servers automatisch und öffnet dessen Autorisierungsseite.

5. Fügen Sie auf dem Bildschirm 🔐 five9-mcp Ihren MCP_AUTH_TOKEN als Zugriffsschlüssel ein und klicken Sie auf Autorisieren.

6. Öffnen Sie in einem beliebigen Chat das Menü Suche & Tools (＋) und stellen Sie sicher, dass der Five9-Connector aktiviert ist.

Team/Enterprise: Ein Besitzer fügt den Connector zunächst unter Organisationseinstellungen → Connectors hinzu; Mitglieder klicken dann in ihren eigenen Einstellungen auf Verbinden, um zu autorisieren.

ChatGPT verbinden

Benutzerdefinierte MCP-Connectors erfordern den Entwicklermodus (Plus/Pro; bei Business/Enterprise muss ein Admin benutzerdefinierte Connectors erlauben).

1. Öffnen Sie in ChatGPT im Web Einstellungen → Apps & Connectors (manchmal auch nur Connectors genannt).

2. Aktivieren Sie unter Erweiterte Einstellungen den Entwicklermodus.

3. Klicken Sie auf der Connectors-Seite auf Erstellen.

4. Nennen Sie ihn Five9, setzen Sie die MCP-Server-URL auf https://<your-worker>.workers.dev/mcp und wählen Sie die Authentifizierung OAuth.

5. Bestätigen Sie die Vertrauensabfrage und speichern Sie. ChatGPT öffnet die Autorisierungsseite dieses Servers — fügen Sie Ihren MCP_AUTH_TOKEN ein und klicken Sie auf Autorisieren.

6. Öffnen Sie in einem neuen Chat das Menü ＋ / Tools und aktivieren Sie den Five9-Connector (Connectors im Entwicklermodus werden pro Unterhaltung aktiviert). ChatGPT fordert Sie auf, jeden Tool-Aufruf zu bestätigen — sinnvoll bei allem, was einen Dialer starten kann. 😄

Claude Code verbinden

claude mcp add --transport http five9 https://<your-worker>.workers.dev/mcp \
  --header "Authorization: Bearer <your MCP_AUTH_TOKEN>"

Der rohe Zugriffsschlüssel funktioniert direkt als Bearer-Token — kein OAuth-Tanz. Führen Sie /mcp in Claude Code aus, um es zu überprüfen.

Jeder andere MCP-Client

Alles, was MCP streamable HTTP unterstützt, funktioniert — schließen Sie den OAuth-Flow ab oder senden Sie den Zugriffsschlüssel als 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 implementiert einen minimalen OAuth-2.1-Autorisierungsserver (Metadaten-Discovery, dynamische Client-Registrierung, PKCE S256, Refresh-Tokens), der für einen Einzelbetreiber-Einsatz ausgelegt ist:

• Das „Login“ auf dem Zustimmungsbildschirm ist der Zugriffsschlüssel des Servers (MCP_AUTH_TOKEN).

• Alles ist zustandslos — Client-IDs, Autorisierungscodes und Tokens sind HMAC-SHA256-signierte Blobs mit MCP_AUTH_TOKEN als Schlüssel. Kein KV, keine Durable Objects.

• Beide Authentifizierungspfade funktionieren gleichzeitig: per OAuth ausgestellte Tokens und der rohe Schlüssel als Bearer-Anmeldedaten.

• Widerrufen Sie alles auf einmal, indem Sie das Secret rotieren: npx wrangler secret put MCP_AUTH_TOKEN.

🧰 Die Toolbox

77 Tools. 🟢 = lesen (immer sicher) · ✏️ = schreiben (ändert Ihre Domäne — der Server weist KIs an, dies zuerst mit Ihnen zu bestätigen)

69 SOAP-Tools (Benutzername/Passwort) + 8 OAuth-New-Platform-REST-Tools (Consumer Key/Secret — siehe OAuth New Platform APIs).

Der Clou: Beschreiben Sie einen Anrufablauf in einem Absatz, und die KI entwirft ihn, zeigt Ihnen ein Mermaid-Diagramm im Chat und stellt ein funktionierendes IVR-Skript bereit. Das Modell improvisiert nie das IVR-XML von Five9: Es füllt ein eingeschränktes JSON-Flowschema (play / menu / business-hours / skill transfer / voicemail / hangup), ein Graph-Validator prüft jeden Zweig und jede Referenz, und deterministischer Code erzeugt Designer-gerechtes XML (Modul-Verdrahtung, Prompt-Kodierung und Feldreihenfolge stammen alle aus echten exportierten Skripten).

Empfohlener Ablauf: validieren → rendern (dem Menschen zeigen!) → Prompts generieren → erstellen → an eine Inbound-Kampagne anhängen. generate_prompt_audio läuft standardmäßig auf Cloudflare Workers AI: kein externes TTS-Konto, kein API-Schlüssel, Bruchteile eines Cents pro Prompt werden dem Cloudflare-Konto belastet, auf dem Sie bereits bereitgestellt haben. ElevenLabs/OpenAI funktionieren ebenfalls, wenn Sie deren Schlüssel-Secrets setzen, und {tts}-Prompts (die eingebaute Roboterstimme von Five9) benötigen überhaupt nichts.

Diese Tools verwenden Five9s moderne OAuth 2.0 "New Platform" REST APIs, nicht die SOAP-APIs, die die oben genannten Tools verwenden. Sie erfordern eine API Access Control-Zugangsberechtigung (Consumer Key/Secret), nicht den SOAP-Benutzernamen/das SOAP-Passwort — siehe OAuth New Platform APIs.

🔐 OAuth New Platform APIs

Neben den SOAP-Tools kann der Server die neueren OAuth 2.0 New Platform REST APIs von Five9 aufrufen (z. B. Circles, Interactions, Prompts, Domain-Metadaten). Diese verwenden eine andere Zugangsberechtigung als der SOAP-Benutzername/das SOAP-Passwort:

• Ein Consumer Key und Consumer Secret der API Access Control, erzeugt in der Five9-Admin Console → API Access Control (eine Controlled-Availability-Funktion). Zum Erzeugen eines solchen Schlüssels wird die Berechtigung security → applications → Create applications benötigt, und das Konto muss auf den Five9 Identity Service migriert sein (Benutzer mit Legacy-API/Agent/Supervisor-Rollen sind von der Migration ausgeschlossen, bis diese Rollen entfernt wurden).

• Konfigurieren Sie sie als Umgebungs-/Secret-Variablen (alle getrennt von den SOAP-Zugangsdaten):

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=...

Führen Sie dann rest_check_connection aus, um den Token-Flow zu bestätigen. Welche Dienste eine Anmeldeinformation erreichen kann, wird durch ihre API-Familie + Scopes bestimmt – all-apis-access gewährt nicht buchstäblich jeden Dienst, und Schreibzugriff ist pro Dienst festgelegt.

Mehrere Anmeldeinformationen / Familien. Jede API-Access-Control-Anmeldeinformation gehört zu einer Familie (die einem Apigee-API-Produkt zugeordnet ist), und diese Familie legt fest, welche Dienste der Schlüssel aufrufen darf. Der Server unterstützt benannte Anmeldeinformationen: default (aus FIVE9_CONSUMER_KEY/SECRET) sowie data-tables (aus FIVE9_DT_CONSUMER_KEY/SECRET). Die Data-Tables-Tools verwenden automatisch die data-tables-Anmeldeinformation; rest_call und rest_check_connection akzeptieren ein credential-Argument, um eine auszuwählen.

Hinweis: Die Getting-Started-Dokumentation von Five9 listet den Token-Endpunkt als /v1/auth/token, aber der Live-Endpunkt ist /oauth2/v1/token (den dieser Client verwendet).

🎨 Anpassen des Betreiberkontexts

src/about.js enthält den Text, der verbundenen KIs über das MCP-Feld instructions und das Tool about bereitgestellt wird: wer den Server betreibt, warum er existiert und wie sich die KI verhalten soll (z. B. „Vor Schreibaktionen bestätigen“). Bearbeiten Sie die Datei, um Ihre eigene Bereitstellung zu beschreiben – sie wird mit dem Kontext des ursprünglichen Betreibers als Beispiel ausgeliefert.

🏗️ Architektur

Kein Build-Schritt, keine Abhängigkeiten – einfache JS-Module in 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

Anfragen sind zustandslos: Jeder MCP-Aufruf öffnet einen neuen Five9-SOAP-Austausch mit HTTP-Basic-Auth. Die Statistics-API erfordert zusätzlich einen setSessionParameters-Aufruf, den get_realtime_stats pro Aufruf durchführt.

• Five9-Endpunkte werden von JAXB generiert und validieren die Reihenfolge der Kindelemente anhand des WSDL. Wenn Sie diesen Server erweitern, rufen Sie das WSDL ab (https://api.five9.com/wsadmin/v13/AdminWebService?wsdl, HTTP-Basic-Auth) und halten Sie die <xs:sequence>-Reihenfolge exakt ein – einschließlich Basistypen wie basicImportSettings, deren Elemente vor denen der Erweiterung kommen.

• addToListCsv erfordert cleanListBeforeUpdate, crmAddMode, crmUpdateMode und listAddMode, obwohl das WSDL die meisten davon als minOccurs="0" markiert.

• Listen-/CRM-Importe sind asynchron: Der Aufruf liefert sofort eine Importkennung; fragen Sie get_import_result ab, um das Ergebnis zu erhalten.

• Die Werte von Kontaktdatensätzen kommen umhüllt zurück (<values><data>…</data></values>); mehrere Antworten liefern ein einzelnes Objekt, wo man ein Ein-Element-Array erwarten würde. toArray() in five9.js normalisiert das.

• Bei den Zeitkriterien von Berichten kommt <end> vor <start> (alphabetische Sortierung durch JAXB).

• Das IVR-xmlDefinition ist das persistierte Format des visuellen Designers: Module sind per GUID verdrahtet (ascendants / singleDescendant / branches), Inline-TTS-Text wird als gzip+base64-speakElement-Dokumente gespeichert, und Geschäftszeitenprüfungen vergleichen die Systemvariablen __DAY__ (SUN=1..SAT=7) und __TIME__ (Minuten seit Mitternacht). ivr.js kapselt das alles.

• getPrompts liefert keine Prompt-IDs (nur Name + Typ). Referenzen auf Datei-Prompts innerhalb von IVR-XML werden mit id 0 + dem Prompt-Namen akzeptiert und serverseitig normalisiert; das übertragene Skript durchläuft einen Round-Trip mit der vom Server vergebenen domainId.

🛡️ Sicherheit

• Five9-Anmeldedaten liegen ausschließlich in Ihrem Cloudflare-Konto – als Worker-Secrets oder (Assistenten-Pfad) in einem Workers-KV-Namespace, im Ruhezustand verschlüsselt. Kein Tool gibt sie jemals zurück, und Wrangler-Secrets überschreiben KV immer.

• Der Einrichtungsassistent ist nur auf einem frischen, unkonfigurierten Server verfügbar – führen Sie ihn direkt nach dem Deployment aus. Nach der Konfiguration erfordert jede Änderung den aktuellen Zugriffsschlüssel, und über Umgebungsvariablen verwaltete Server lehnen Assistentenänderungen grundsätzlich ab.

• Schließen Sie die Einrichtung immer ab (oder setzen Sie MCP_AUTH_TOKEN). Ein unkonfigurierter Server ohne Zugriffsschlüssel läuft offen – jeder, der die URL findet, kann Ihr Contact Center steuern.

• Schreibwerkzeuge (✏️ oben) verändern Ihre Domain. Begrenzen Sie die Rolle des Five9-API-Benutzers auf das, was eine KI tatsächlich tun soll – Five9-Berechtigungen sind die eigentliche Sicherheitsgrenze.

• manage_dnc remove und delete_list erfordern besondere Vorsicht; die about-Anweisungen sagen den KIs, dass sie vor der Verwendung bestätigen sollen.

• Die Konsole speichert Ihren Zugriffsschlüssel ausschließlich im localStorage Ihres Browsers, und Aufrufe gehen Same-Origin an Ihren eigenen Worker.

💻 Entwicklung

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

Legen Sie lokale Secrets in .dev.vars ab (per Git ignoriert):

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=...

Öffnen Sie dann http://localhost:8787/console, fügen Sie dev-local-token ein und führen Sie die Tools gegen Ihre Domain aus – oder führen Sie von der CLI aus mit dem obigen curl-Snippet einen Smoke-Test durch.

🤝 Mitwirken

PRs sind willkommen! Die Five9-Config-API hat ~180 Operationen, und dieser Server kapselt 69 der nützlichsten – das Muster in five9.js + tools.js lässt sich leicht erweitern (lesen Sie zuerst die SOAP-Anmerkungen und ersparen Sie sich einen Kampf mit dem WSDL). Bitte halten Sie die Vorgabe der Null-Abhängigkeiten ein.

📄 Lizenz

MIT · erstellt von Ryan Shatzkamer