☎️ five9-mcp

Ihr Five9-Contact-Center – in den Händen Ihrer KI.

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

Schnellstart · Claude verbinden · ChatGPT verbinden · Tools · Architektur

Stellen Sie Ihrer KI Fragen wie:

„Wer ist gerade in einem Anruf, und wie tief ist die Vertriebs-Warteschlange?“ 📊 „Erstellen Sie eine Vorschau-Kampagne für die Win-Back-Liste, hängen Sie den Vertriebsskill an und starten Sie sie.“ 🛠️ „Stoppen Sie die OUTBOUND_AGED-Kampagne und fügen Sie diese 3 Leads zur Rückruf-Liste hinzu.“ 📞 „Bringen Sie den neuen Agenten an Board: Legen Sie den Benutzer an und weisen Sie den Billing-Skill auf Stufe 2 zu.“ 🧑💼 „Steht 555-867-5309 auf unserer DNC-Liste? Prüfen Sie das, bevor die Nummer gewählt wird.“ 🚫 „Rufen Sie den Call-Log-Bericht von gestern ab und fassen Sie die Abandon-Raten zusammen.“ 📈 „Bauen Sie 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 Five9 Configuration (Admin) und Statistics (Supervisor) SOAP-Web-Webdienste – dieselben APIs, die bis heute die Five9-Admin-Oberfläche betreiben – und stellt sie als saubere JSON-Tools über MCP Streamable HTTP bereit. Handgebaute Envelopes, ein XML-Parser mit rund 60 Zeilen, keine npm-Pakete. Jedes Tool wurde gegen eine Live-Five9-Umgebung getestet.

✨ Integrierte Web-UI

Stellen Sie den Worker bereit, und er liefert mehr als eine API:

Die Konsole ist der schnellste Weg, um Zugangsdaten zu testen, die Ausgaben der Tools zu erkunden oder eine Kampagne zu debuggen – ganz ohne KI.

Related MCP server: five9-mcp

🚀 Schnellstart – kein Terminal nötig

Sie benzert ein kostenloses Cloudflare-Konto und einen Five9-Benutzer mit API-Zugriff –ereigen Sie einen dedizierten Five9-API-Benutzer ein, der genau die Berechtigungen erhält, die die KI haben soll, und auf einen persönlichen Admin-Login verzichtenpäd.hat.

1 – Bereitstellung auf Cloudflare (ein Klick, in Ihrem Browser)

Melden Sie sich bei Cloudflare an und klicken Sie sich durch: Die Bereitstellung erstellt eine eigene Kopie dieses Workers (einschließlich des benötigten KV-Namespace) und gibt Ihnen eine URL wie https://five9-mcp.yourname.workers.dev.

2 – Setup-Assistent ausführen (in Ihrem Browser)

Open /setup auf Ihrem neuen Server. Geben Sie Ihren Five9-Benutzernamen, das Passwort und die Region ein – der Assistent prverifiziert die Daten live gegen Five9, bevor er sie speichert, und übergibt Ihnen anschließend Ihren Zugriffsschlüssel (wird nur einmal anzeigt – hebden Sie ihn in einem Passwort-Manager sicher auf).

3 – Ihre KI verbinden (Anbindungsanleitungen unter) und fragen Sie sie z. B.: „Prüfe the Verbindung and listest meine Kampagne auf." 🎉

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

Nutzen Sie dann entweder den /setup-Assistenten oder überspringen Sie ihn und verwalten Sie die Zugangsbasierte Daten als Wrangler-Secrets (Secrets haben Vorrang vor dem 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 funkfür US-Regionen:

• Standard | Hinweise

• FIVE9_API_HOST | Standard: api.five9.com | EU: api.eu.five9.com · Kanada: api.ca.five9.com

• FIVE9_ADMIN_VERSION | Standard: v13 | Config-Web-Services-WSDL-Version

• FIVE9_SUPERVISOR_VERSION | Standard: v13 | Statistics-Web-Services-CCSDL-Version

🔌 Verbinden Sie Ihre KI

Claude verbinden (Web & Desktop)

Benutzerdefinierte Connector gibt es in den Tarifen Free (ein Connector), Pro, Max, Team und Enterprise.

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

2. Klicken Sie auf Custom Connector hinzufügen.

3. Nennen Sie ihn Five, und fügen Sie die URL Ihres Servers einschließlich des /mcp- Pfads ein: https://<your-worker>.workers.dev/mcp.

4. Klicken auf Hinzufügen und dann auf Verbinden. Claude erstellt das integrierte OAuth dieses Servers automatisch und pffnet die Autorisierungsseite.

5. Auf den B griff auf 🔐 fyein9-mcp den MCP_AUTH_TOKEN als Zugriffsschlüssel ein und klicken Sie auf Autorisieren.

6. In einem Chat geöffnet Menü Suche & Tools (＋) und stellen Sie sicher, dass der Five9-Connector aktiviert ist.

Windows-/Enterprise-KKunden: Ein Owner fügt der Connector zunächst unter Organisationseinstellungen → Connector hinzu; Mitglieder klicken dann in ihren eigenen Einstellungen auf Verbinden, um to Authorize.

ChatGPT verbinden

Benutzerdefinierte MCP-Connectors sind im Entwicklermodus, möglich (Plus/Pro; in Business/Enterprise achten Admins populationend erst).

1. Öffnen Sie [ChatGPT] (https://chatgpt.com) im Browser Einstellungen → Apps & Connectors (manchmal nur Connectors).

2. Aktivieren Sie unter Erweiterte Einstellungen den Entwicklermodus.

3. Klicken Sie auf die Connectors-Seite Erstellen.

4. Nennen Sie den Connector Five9, setzen The MCP-Server-URL auf https://<your-worker>.workers.dev/mcp and select the OAuth authentication.

5. Bestätigen Sie den Vertrauenshinweis weiden Sie speichern. ChatGPT pffnet die Autorisierungsseite dieses Servers – fügen Sie Ihren MCP_AUTH_TOKEN ein und klicken Sie auf Autorisieren.

6. In a new chat sie funnel plus ／Tools-Menü open and the Five connector activation (connectors of the developer mode are enabled pro conversation). Teaser p passes each tool call from ChatGPT – sensible if you do start a few jobs. 😄

Claude Code verbinden

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

Der rohe Schlüssel funktioniert direkt als Bearer-Token – kein OAuth-Tanz. Führen Sie in Claude Code /mcp aus, um die Verbindung zu prüfen.

Diesiges anderes MCP-Clienten

Jede MCP-Streamable-HTTP-Integration funktioniert – führen Sie den OAuth-Ablauf durch oder send 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 minimalistischen OAuth 2.1-Authorisierungsserver (Bekanntmachungsermittlung, dynamische Client-Registrierung PKCE TE S256, Refresh-Tokens) eing für einzelne Betreiber models:

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

• Alles ist zustandslos – Client-IDs, Auth-Codes und Token sind mit MCP_AUTH_TOKEN signierte HMAC-SHA256-Blobs. Keine KV, keine Durable Objects.

• Beide Auth-Wege funktionieren gleichzeitig: OAuth-ausgestellte Token und der rohe Key als Betrag.

• Widerrufe everything auf once, as the secret rotatieren: npx wrangler secret put MCP_AUTH_TOKEN.

🧰 Die Toolbox

77 Werkzeuge. 🟢 = read-only (immer sicher) · ✏️ = schreibend (verändert Ihre Umgebung – die server weist die KI an, dies vorher mit Ihnen abzustreichen)

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 einen Absatz, und die KI entwirft ihn daraus, zeigt ein Mermaid-Diagramm im Chat und implementiert ein lauffähiges IVR-Script. Damit das Modell das gege Überbegriff mit „Five9-IVR-XML“ erfindet: Es füllt eine begrenzte JSON-Flow-Spezifikation (play / menu / ruftym / business hours / skill transfer / voicemail / hangup), ein Tool prüft als Graph jede Verzweigung und Referenz, und deterministischer Code erzeugt das XML in Designer-Form – alle Modulverbindungen, Formatierung eines Hi-Fi-Formats with a15; verwendung und Feldreihenfolge werden aus realen exportierten Skripten abgeleitet.

Empfohlener Ablauf: validate → render (erst dem Menschen zeigen!) → prompts generieren → build → in einer Inbound-Kampagne zuordnen. generate_prompt_audio funktioniert out of the box mit Cloudflare Workers AI; kein extern TTS-Programm und kein API-Key, nur Bruchteile eines Cents pro Ansage, die über das bereits eingerichtete Cloudflare-Konto verarbeitet werden. ElevenLabs/OpenAI funktionieren ebenfalls, wenn Sie den passenden Schlüssel-Secret setzen, und {tts}-Prompts (die eingebaute Roboter-Stimmt von Five9) benötigen nichts weiter.

Diese Tools verwenden die modernen OAuth-2.0-"New-Platform"-REST-APIs von Five9, nicht die SOAP-APIs. Sie erfordern eine API-Access-Control-Zugangsdaten (Consumer Key/Secret), nicht das SOAP-Benutzerkonto/Passwort — siehe OAuth New Platform APIs.

🟢 OAuth New-Platform-APIs

Neben den SOAP-Werkzeugen 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 Zugangsdaten als den SOAP-Benutzernamen/das Passwort:

• Ein API Access Control Consumer Key und Consumer Secret, generiert in der Five9 Admin Console → API Access Control (ein Controlled-Availability-Feature). Zum Erzeugen wird die Berechtigung security → applications → Create applications benötigt, und das Konto muss zum Five9 Identity Service migriert worden sein (Benutzer mit Legacy-API/Agent/Supervisor-Rollen sind von der Migration ausgeschlossen, bis diese Rollen entfernt wurden).

• Konfigurieren Sie sie als Env-/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-Fluss zu bestätigen. Welche Dienste eine Anmeldeinformation erreichen kann, wird durch ihre API-Familie + Scopes bestimmt — all-apis-access gewährt nicht wörtlich Zugriff auf jeden Dienst, und Schreibzugriff gilt pro Dienst.

Mehrere Anmeldeinformationen / Familien. Jede API-Access-Control-Anmeldeinformation gehört zu einer Familie (zugeordnet zu einem Apigee-API-Produkt), und diese Familie bestimmt, 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 zur Auswahl.

Hinweis: Five9s Einstiegsdokumentation listet den Token-Endpunkt als /v1/auth/token, aber der tatsächlich aktive Endpunkt ist /oauth2/v1/token (den dieser Client verwendet).

🎨 Betreiberkontext anpassen

src/about.js enthält den Text, der verbundenen KIs über das MCP-instructions-Feld und das about-Tool bereitgestellt wird: Wer den Server betreibt, warum er existiert und wie sich die KI verhalten soll (z. B. „Vor Schreibvorgängen 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-Authentifizierung. Die Statistics API erfordert zusätzlich einen setSessionParameters-Aufruf, den get_realtime_stats pro Aufruf ausführt.

• Die Endpunkte von Five9 werden von JAXB generiert und validieren die Reihenfolge der Kindelemente anhand der WSDL. Wenn Sie diesen Server erweitern, ziehen Sie sich die WSDL (https://api.five9.com/wsadmin/v13/AdminWebService?wsdl, HTTP-Basic-Authentifizierung) und gleichen Sie die <xs:sequence>-Reihenfolge exakt ab — einschließlich Basistypen wie basicImportSettings, deren Elemente vor denen der Erweiterung stehen.

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

• Listen-/CRM-Importe sind asynchron: Der Aufruf gibt sofort eine Import-Kennung zurück; fragen Sie das Ergebnis über get_import_result ab.

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

• Die Reihenfolge der Zeitkriterien für Reports lautet <end> vor <start> (alphabetische JAXB-Sortierung).

• Die IVR-xmlDefinition ist das persistierte Format des visuellen Designers: Module werden über GUIDs verdrahtet (ascendants / singleDescendant / branches); Inline-TTS-Text wird als gzip+base64-speakElement-Dokumente gespeichert, und Geschäftszeiten-Checks vergleichen die Systemvariablen __DAY__ (SUN=1..SAT=7) und __TIME__ (Minuten seit Mitternacht). ivr.js kapselt all das.

• getPrompts gibt keine Prompt-IDs zurück (nur Name + Typ). Datei-Prompt-Referenzen innerhalb von IVR-XML werden mit id 0 und dem Prompt-Namen akzeptiert und serverseitig normalisiert; das übertragene Skript wird ausgeliefert, enthält aber die serverseitig vergebene domainId.

🛡️ Sicherheit

• Five9-Zugangsdaten liegen nur in Ihrem Cloudflare-Konto — als Worker-Secrets oder (Wizard-Pfad) in einem Workers-KV-Namespace, im Ruhezustand verschlüsselt. Kein Tool gibt sie jemals zurück, und Wrangler-Secrets haben stets Vorrang gegenüber KV.

• Der Einrichtungsassistent ist nur auf einem frischen, noch nicht konfigurierten Server verfügbar — führen Sie ihn direkt nach dem Deployment aus. Nach der Konfiguration erfordert jede Änderung den aktuellen Access-Key, und per Env-Variablen verwalteten Server lehnen Assistenten-Änderungen vollständig ab.

• Schließen Sie die Einrichtung immer ab (oder setzen Sie MCP_AUTH_TOKEN). Ein nicht konfigurierter Server ohne Access-Key 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 — die Five9-Berechtigungen sind die eigentliche Sicherheitsgrenze.

• manage_dnc remove und delete_list erfordern besondere Vorsicht; die about-Anweisungen sagen den KIs, vor der Verwendung eine Bestätigung einzuholen.

• Die Konsole speichert Ihren Access-Key nur im localStorage des Browsers; die Aufrufe erfolgen 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 (gitignored):

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

Dann öffnen Sie http://localhost:8787/console, fügen Sie dev-local-token ein und führen Sie die Tools gegen Ihre Domain aus — oder rauchen Sie von der CLI aus einen Smoke-Test mit dem curl-Ausschnitt oben.

🤝 Mitwirken

PRs willkommen! Die Five9-Config-API-Operationen umfassen etwa 180, 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-Hinweise und ersparen sich einen Kampf mit der WSDL). Bitte behalten Sie die Zero-Dependency-Einschränkung bei.

📄 Lizenz

MIT · entwickelt von Ryan Shatzkamer