☎️ five9-mcp

Dein Five9-Contact-Center in den Händen deiner KI.

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

Schnellstart · Claude verbinden · ChatGPT verbinden · Tools · Architektur

Frag deine KI zum Beispiel:

„Wer ist gerade in einem Anruf und wie tief ist die Verkaufs-Warteschlange?“ 📊 „Erstelle eine Preview-Kampagne für die Win-back-Liste, weise den Verkaufs-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 den Abrechnungs-Skill auf Stufe 2 zu.“ 🧑💼 „Ist 555-867-5309 auf unserer DNC-Liste? Prüfe das, bevor jemand die Nummer wählt.“ 🚫 „Hole den gestrigen Call-Log-Bericht und fasse die Abandon-Raten zusammen.“ 📈 „Baue mir eine komplette IVR: Option 1 Terminplanung, Option 2 Abrechnung, außerhalb der Geschäftszeiten geht es an die Voicemail.“ 🧩

Unter der Haube spricht dieser Server mit den SOAP-Web-Services von Five9s Configuration (admin) und Statistics (supervisor) – den APIs, die noch immer Five9s 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 Live-Five9-Domain getestet.

✨ Integrierte Web-UI

Stell es bereit und dein Worker liefert mehr als eine API:

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

Related MCP server: five9-mcp

🚀 Schnellstart – kein Terminal nötig

Du brauchst ein kostenloses Cloudflare-Konto und einen Five9-Benutzer mit API-Zugriff – erstelle einen dedizierten Five9-API-Benutzer, der genau auf das beschränkt ist, was eine KI tun soll, und verwende nicht erneut einen persönlichen Admin-Login.

1 – Bei Cloudflare bereitstellen (ein Klick, im Browser)

Melde dich bei Cloudflare an und klicke durch – es erstellt deine eigene Kopie dieses Workers (plus den benötigten KV-Namespace) und gibt dir eine URL wie https://five9-mcp.you.workers.dev.

2 – Den Setup-Assistenten ausführen (im Browser)

Öffne /setup auf deinem neuen Server. Gib deinen Five9-Benutzernamen, dein Passwort und deine Region ein – der Assistent verifiziert sie live gegen Five9, bevor er speichert, und übergibt dir dann deinen Zugriffsschlüssel (wird nur einmal angezeigt – bewahre ihn in einem Passwort-Manager auf).

3 – Verbinde deine KI (Anleitungen unten) und bitte sie dann, „die Verbindung zu prü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

Nutze dann entweder den /setup-Assistenten oder überspringe ihn und verwalte die 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 funktionieren für US-Domains:

🔌 Verbinde deine KI

Claude verbinden (Web & Desktop)

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

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

2. Klicke auf Benutzerdefinierten Connector hinzufügen.

3. Nenne ihn Five9 und füge deine Server-URL einschließlich des /mcp-Pfads ein: https://<your-worker>.workers.dev/mcp

4. Klicke auf Hinzufügen, dann auf Verbinden. Claude erkennt das integrierte OAuth dieses Servers automatisch und öffnet seine Autorisierungsseite.

5. Füge auf dem Bildschirm 🔐 five9-mcp deinen MCP_AUTH_TOKEN als Zugriffsschlüssel ein und klicke auf Autorisieren.

6. Öffne in einem beliebigen Chat das Menü Suchen & Tools (＋) und stelle sicher, dass der Five9-Connector aktiviert ist.

Team/Enterprise: Ein Owner 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 Admin benutzerdefinierte Connectors erlauben).

1. Öffne in ChatGPT im Web Einstellungen → Apps & Connectors (manchmal auch nur als Connectors bezeichnet).

2. Aktiviere unter Erweiterte Einstellungen den Entwicklermodus.

3. Klicke zurück auf der Connectors-Seite auf Erstellen.

4. Nenne ihn Five9, setze die MCP-Server-URL auf https://<your-worker>.workers.dev/mcp und wähle die OAuth-Authentifizierung.

5. Bestätige den Vertrauenshinweis und speichere. ChatGPT öffnet die Autorisierungsseite dieses Servers – füge deinen MCP_AUTH_TOKEN ein und klicke auf Autorisieren.

6. Öffne in einem neuen Chat das Menü ＋ / Tools und aktiviere den Five9-Connector (Connectors im Entwicklermodus werden pro Konversation aktiviert). ChatGPT fragt dich bei jedem Tool-Aufruf um Bestätigung – 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ühre /mcp in Claude Code aus, um es zu überprüfen.

Jeder andere MCP-Client

Alles, was MCP streamable HTTP spricht, funktioniert – schließe den OAuth-Flow ab oder sende 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 (Metadata-Discovery, dynamische Client-Registrierung, PKCE S256, Refresh-Tokens), der für eine Einzelbetreiber-Bereitstellung ausgelegt ist:

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

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

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

• Widerrufe alles auf einmal durch Rotieren des Secrets: npx wrangler secret put MCP_AUTH_TOKEN.

🧰 Die Toolbox

77 Tools. 🟢 = Lesen (immer sicher) · ✏️ = Schreiben (ändert deine Domain – der Server weist die KIs an, zuerst deine Bestätigung einzuholen)

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

Der Clou: Beschreibe einen Anrufablauf in einem Absatz und die KI entwirft ihn, zeigt dir ein Mermaid-Diagramm im Chat und stellt ein funktionierendes IVR-Skript bereit. Das Modell erfindet Five9s IVR-XML nie frei: Es füllt eine eingeschränkte JSON-Flow-Spezifikation (play / menu / business-hours / skill transfer / voicemail / hangup), ein Graph-Validator prüft jeden Zweig und jede Referenz, und deterministischer Code erzeugt Designer-konformes XML (Modulverdrahtung, Prompt-Kodierung und Feldreihenfolge stammen alle aus echten exportierten Skripten).

Empfohlener Ablauf: validieren → rendern (dem Menschen zeigen!) → Prompts erzeugen → bauen → an eine Inbound-Kampagne anhängen. generate_prompt_audio läuft sofort auf Cloudflare Workers AI: kein externes TTS-Konto, kein API-Key, Bruchteile eines Cents pro Prompt, abgerechnet über das Cloudflare-Konto, auf dem du bereits deployed hast. ElevenLabs/OpenAI funktionieren ebenfalls, wenn du ihre Key-Secrets setzt, und {tts}-Prompts (Five9s eingebaute Roboterstimme) brauchen gar nichts.

Diese Tools verwenden Five9s moderne OAuth 2.0 "New Platform" REST-APIs, nicht die SOAP-APIs, die die obigen Tools verwenden. Sie erfordern eine API Access Control-Anmeldeinformation (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 Five9s neuere OAuth 2.0 New Platform REST-APIs aufrufen (z. B. Circles, Interactions, Prompts, Domain-Metadaten). Diese verwenden eine andere Anmeldeinformation als der SOAP-Benutzername/das SOAP-Passwort:

• Ein API Access Control-Consumer Key und Consumer Secret, erzeugt 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 werden (Benutzer mit veralteten API-/Agent-/Supervisor-Rollen werden von der Migration ausgeschlossen, bis diese Rollen entfernt wurden).

• Konfiguriere 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ühre dann rest_check_connection aus, um den Token-Fluss zu bestätigen. Was jedes Credential erreichen kann, bestimmen seine API-Familie + Scopes – all-apis-access gewährt nicht buchstäblich jeden Dienst, und der Schreibzugriff ist pro Dienst festgelegt.

Mehrere Credentials / Familien. Jedes API-Access-Control-Credential gehört zu einer Familie (abgebildet auf ein Apigee-API-Produkt), und diese Familie entscheidet, welche Dienste der Schlüssel aufrufen darf. Der Server unterstützt benannte Credentials: default (aus FIVE9_CONSUMER_KEY/SECRET) plus data-tables (aus FIVE9_DT_CONSUMER_KEY/SECRET). Die Data-Tables-Tools verwenden automatisch das data-tables-Credential; rest_call und rest_check_connection akzeptieren ein credential-Argument, um eines auszuwählen.

Hinweis: Five9s Einstiegsdokument nennt den Token-Endpunkt /v1/auth/token, aber der tatsächliche Endpunkt ist /oauth2/v1/token (und diesen verwendet dieser Client).

🎨 Den Betreiber-Kontext anpassen

src/about.js enthält den Text, der verbundenen AIs über das MCP-instructions-Feld und das about-Tool bereitgestellt wird: wer den Server betreibt, warum es ihn gibt und wie sich die AI verhalten soll (z. B. „vor Schreibaktionen bestätigen“). Bearbeite ihn, um dein eigenes Deployment zu beschreiben – er 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

Alle 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 bei jedem Aufruf ausführt.

• Five9s Endpunkte werden von JAXB generiert und validieren die Reihenfolge der Kind-Elemente gegen die WSDL-Sequenz. Wenn du diesen Server erweiterst, ziehe dir das WSDL (https://api.five9.com/wsadmin/v13/AdminWebService?wsdl, HTTP-BasisAuth) und gleiche 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 das WSDL die meisten davon als minOccurs="0" markiert.

• Listen-/CRM-Importe sind asynchron: Der Aufruf gibt sofort eine Import-ID zurück; frage get_import_result ab, um das Ergebnis zu erfahren.

• Kontaktwerte werden verpackt zurückgegeben (<values><data>…</data></values>); einige Antworten liefern ein einzelnes Objekt, wo man ein Ein-Element-Array erwarten würde. toArray() in five9.js normalisiert das.

• Bei Zeitkriterien von Reportings kommt <end> vor <start> (alphabetische JAXB-Reihenfolge).

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

• getPrompts gibt keine Prompt-IDs zurück (nur Name + Typ). Datei-Prompt-Referenzen in IVR-XML werden mit id 0 + dem Prompt-Namen akzeptiert und serverseitig normalisiert; das übertragene Skript läuft mit der serverseitig vergebenen domainId im Roundtrip.

🛡️ Sicherheit

• Five9-Zugangsdaten liegen ausschließlich in deinem Cloudflare-Konto – als Worker-Secrets oder (im Wizardverlauf) in einem Workers-KV-Namespace, verschlüsselt im Ruhezustand. Kein Tool gibt sie jemals zurück, und Wrangler-Secrets haben immer Vorrang vor KV.

• Der Setup-Assistent ist nur auf einem frischen, unkonfigurierten Server geöffnet – führe ihn direkt nach dem Deployment aus. Ist er erst konfiguriert, erfordert jede Änderung den aktuellen Zugriffsschlüssel, und per Envvnie verwaltete Server lehnen Änderungen über den Assistenten vollständig ab.

• Schließe das Setup immer ab (oder setze MCP_AUTH_TOKEN). Ein unkonfigurierter Server ohne Zugriffsschlüssel bleibt offen – jeder, der die URL findet, kann dein Contact-Center steuern.

• Schreib-Tools (✏️ oben) verändern deine Domain. Drossle die Rolle des Five-9-API-Benutzers auf das, was du von einer AI erwartest – die Five9-Berechtigungen bilden die eigentliche Sicherheitsgrenze.

• manage_dnc remove und delete_list erfordern besondere Vorsicht; die about-Anweisungen weisen AIs an, vor der Verwendung eine Bestätigung einzuholen.

• Die Konsole speichert deinen Zugriffsschlüssel nur im localStorage des Browsers, und die Aufrufe werden gleich-originig zu deinem eigenen Worker ausgeführt.

💻 Entwicklung

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

Lege lokale Secrets in .dev.vars an (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=...

Öffne dann http://localhost:8787/console, füge dev-local-token ein und führe Tools gegen deine Domain aus – oder teste von der CLI mit dem curl-Snippet oben.

🤝 Mitwirken

PRs sind willkommen! Die Five9-Config-API kann ~180-Operationen und dieser Server kapselt 69 der nützlichsten – das Muster in five9.js + tools.js ist leicht anpassend (lies zuerst die SOAP-Anmerkungen und spar dir den Kampf mit. WSDL). Bitte halte am der Null-Abhängigkeits-Einschränkung fest.

📄 Lizenz

MIT · erstellt von [Ryan