☎️ five9-mcp

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

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

Schnellstart · Claude verbinden · ChatGPT verbinden · Tools · Architektur

Fragen Sie Ihre KI Dinge wie:

„Wer ist gerade in einem Gespräch und wie tief ist die Vertriebs-Warteschlange?" 📊 „Erstelle eine Preview-Kampagne für die Rückgewinnungsliste, weise die Vertriebs-Skill zu und starte sie." 🛠️ „Stoppe die OUTBOUND_AGED-Kampagne und füge diese 3 Leads zur Rückrufliste hinzu." 📞 „Binde den neuen Agenten ein: Erstelle den Benutzer, weise die Abrechnungs-Skill auf Stufe 2 zu." 🧑💼 „Ist 555-867-5309 in unserer DNC? Überprüfe, bevor jemand anruft." 🚫 „Hole den gestrigen Anrufprotokollbericht und fasse die Abbruchraten zusammen." 📈 „Baue mir eine komplette IVR: Option 1 Terminplanung, Option 2 Abrechnung, außerhalb der Geschäftszeiten geht es zur Voicemail." 🧩

Im Hintergrund spricht dieser Server mit Five9s Konfigurations- (Admin) und Statistik- (Supervisor) SOAP-Webdiensten – den APIs, die noch immer Five9s Admin-Oberfläche betreiben – und stellt sie als saubere JSON-Tools über MCP streamable HTTP bereit. Handgefertigte Envelopes, ein ~60-zeiliger XML-Parser, keine npm-Pakete. Jedes Tool wurde gegen eine echte Five9-Domain getestet.

✨ Integrierte Weboberfläche

Stellen Sie es bereit und Ihr Worker dient mehr als nur einer API:

Die Konsole ist der schnellste Weg, um Anmeldedaten zu überprüfen, zu erkunden, was jedes Tool zurückgibt, oder eine Kampagne zu debuggen – keine KI erforderlich.

Related MCP server: five9-mcp

🚀 Schnellstart – kein Terminal erforderlich

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

1 – Bei Cloudflare bereitstellen (ein Klick, in Ihrem Browser)

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

2 – Führen Sie den Setup-Assistenten aus (in Ihrem Browser)

Öffnen Sie /setup auf Ihrem neuen Server. 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 Zugangsschlüssel (einmal angezeigt – speichern Sie ihn in einem Passwort-Manager).

3 – Verbinden Sie Ihre KI (Anleitungen unten), und bitten Sie sie dann, „die Verbindung zu überprüfen und meine Kampagnen aufzulisten." 🎉

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

Dann verwenden Sie entweder den /setup-Assistenten oder überspringen Sie ihn und verwalten Sie die Anmeldedaten 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

Standardwerte befinden sich in wrangler.toml und funktionieren für US-Domains:

🔌 Verbinden Sie Ihre KI

Claude verbinden (Web & Desktop)

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

1. Öffnen Sie in claude.ai oder 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, dann auf Verbinden. Claude erkennt automatisch das integrierte OAuth dieses Servers und öffnet seine Autorisierungsseite.

5. Fügen Sie auf dem 🔐 five9-mcp-Bildschirm Ihren MCP_AUTH_TOKEN als Zugangsschlü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 zuerst 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 Administrator 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. Gehen Sie zurück zur Connectors-Seite und klicken Sie auf Erstellen.

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

5. Bestätigen Sie die Vertrauensaufforderung 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 ＋ / Tools-Menü und aktivieren Sie den Five9-Connector (Entwicklermodus-Connectors werden pro Konversation aktiviert). ChatGPT bittet Sie, jeden Tool-Aufruf zu bestätigen – sinnvoll für alles, 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 Zugangsschlüssel funktioniert direkt als Bearer-Token – kein OAuth-Tanz. Führen Sie /mcp in Claude Code aus, um zu überprüfen.

Jeder andere MCP-Client

Alles, was MCP streamable HTTP spricht, funktioniert – führen Sie den OAuth-Fluss durch oder senden Sie den Zugangsschlü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-Erkennung, dynamische Client-Registrierung, PKCE S256, Refresh-Tokens), der für einen Einzelbetreiber-Einsatz ausgelegt ist:

• Der „Login" auf dem Zustimmungsbildschirm ist der Zugangsschlüssel des Servers (MCP_AUTH_TOKEN).

• Alles ist zustandslos – Client-IDs, Autorisierungscodes und Token sind HMAC-SHA256-signierte Blobs, die mit MCP_AUTH_TOKEN verschlüsselt sind. Kein KV, keine Durable Objects.

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

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

🧰 Die Werkzeugkiste

77 Tools. 🟢 = lesen (immer sicher) · ✏️ = schreiben (ändert Ihre Domain – der Server teilt der KI mit, dass sie zuerst Ihre Bestätigung einholen soll)

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

Der Haupttrick: 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 Five9s IVR-XML: Es füllt eine eingeschränkte JSON-Fluss-Spezifikation (Play / Menü / Geschäftszeiten / Skill-Transfer / Voicemail / Auflegen), ein Graph-Validator prüft jeden Zweig und jede Referenz, und deterministischer Code erzeugt designerförmiges XML (Modulverdrahtung, Prompt-Kodierung und Feldreihenfolge alle aus echten exportierten Skripten abgeleitet).

Empfohlener Ablauf: validieren → rendern (dem Menschen zeigen!) → Prompts generieren → bauen → an eine Inbound-Kampagne anhängen. generate_prompt_audio läuft sofort auf Cloudflare Workers AI: kein externes TTS-Konto, kein API-Schlüssel, Bruchteile eines Cents pro Prompt, abgerechnet über das Cloudflare-Konto, auf dem Sie bereits bereitgestellt haben. ElevenLabs/OpenAI funktionieren auch, wenn Sie deren Schlüssel-Geheimnisse setzen, und {tts}-Prompts (Fivegs eingebaute Roboterstimme) benötigen überhaupt nichts.

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

🔐 OAuth New Platform APIs

Neben den SOAP-Tools kann der Server Five9s neuere OAuth 2.0 New Platform REST APIs aufrufen (z.B. Kreise, Interaktionen, Ansagen, Domain-Metadaten). Diese verwenden eine andere Anmeldedaten als der SOAP-Benutzername/das Passwort:

• Ein API Access Control Consumer Key und Consumer Secret, generiert in der Five9 Admin Console → API Access Control (eine Funktion mit kontrollierter Verfügbarkeit). Zum Generieren wird die Berechtigung security → applications → Create applications benötigt, und das Konto muss zum Five9 Identity Service migriert sein (Benutzer mit Legacy-API/Agent/Supervisor-Rollen werden von der Migration ausgeschlossen, bis diese Rollen entfernt wurden).

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

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 Ressourcen mit einer Anmeldeinformation erreicht werden können, 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 (zugeordnet zu einem Apigee API Product), und diese Familie bestimmt, welche Dienste der Schlüssel aufrufen darf. Der Server unterstützt benannte Anmeldeinformationen: default (aus FIVE9_CONSUMER_KEY/SECRET) plus 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: Five9s Einstiegsdokumentation listet den Token-Endpunkt als /v1/auth/token, aber der Live-Endpunkt ist /oauth2/v1/token (den dieser Client verwendet).

🎨 Anpassen des Operator-Kontexts

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 ihn, um Ihre eigene Bereitstellung zu beschreiben – er wird mit dem ursprünglichen Operator-Kontext 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 durchführt.

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

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

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

• Kontaktdatensatzwerte werden umschlossen zurückgegeben (<values><data>…</data></values>); mehrere Antworten geben ein einzelnes Objekt zurück, wo man ein Ein-Element-Array erwarten würde. toArray() in five9.js normalisiert dies.

• Die Reihenfolge der Berichtszeitkriterien ist <end> vor <start> (JAXB-alphabetische Sortierung).

• IVR xmlDefinition ist das persistierte Format des visuellen Designers: Module sind über GUIDs 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 all dies.

• getPrompts gibt keine Prompt-IDs zurück (nur Name + Typ). Datei-Prompt-Referenzen innerhalb von IVR-XML werden mit id 0 + dem Prompt-Namen akzeptiert und serverseitig normalisiert; das gepushte Skript durchläuft einen Roundtrip mit der vom Server vergebenen domainId.

🛡️ Sicherheit

• Five9-Anmeldeinformationen leben nur in Ihrem Cloudflare-Konto – als Worker-Secrets oder (Wizard-Pfad) in einem Workers KV-Namespace, verschlüsselt im Ruhezustand. Kein Tool gibt sie jemals zurück, und Wrangler-Secrets überschreiben immer KV.

• Der Setup-Wizard ist nur auf einem frischen, unkonfigurierten Server geöffnet – führen Sie ihn direkt nach der Bereitstellung aus. Nach der Konfiguration erfordert jede Änderung den aktuellen Zugriffsschlüssel, und umgebungsverwaltete Server verweigern Wizard-Änderungen vollständig.

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

• Schreib-Tools (✏️ oben) ä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 teilen KIs mit, vor der Verwendung zu bestätigen.

• Die Konsole speichert Ihren Zugriffsschlüssel nur im localStorage Ihres Browsers, und Aufrufe erfolgen gleichherkunft zu Ihrem eigenen Worker.

💻 Entwicklung

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

Legen Sie lokale Secrets in .dev.vars (gitignoriert) ab:

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 Tools gegen Ihre Domain aus – oder testen Sie von der CLI mit dem obigen curl-Snippet.

🤝 Beitragen

PRs willkommen! Die Five9 Config-API hat ~180 Operationen und dieser Server umfasst 69 der nützlichsten – das Muster in five9.js + tools.js ist einfach zu erweitern (lesen Sie zuerst die SOAP-Anmerkungen und ersparen Sie sich den Kampf mit der WSDL). Bitte halten Sie die Null-Abhängigkeits-Einschränkung ein.

📄 Lizenz

MIT · erstellt von Ryan Shatzkamer