☎️ five9-mcp

あなたの Five9 コンタクトセンターを、あなたの AI の手に。

Claude、ChatGPT、または任意の MCP クライアントを Five9 クラウドコンタクトセンターへ接続するオープンソースの MCP サーバーです。Cloudflare Workers 上で動作し、依存関係ゼロです。

クイックスタート・Claude を接続・ChatGPT を接続・ツール・アーキテクチャー

AI にこんなことを頼んでみましょう：

"今、誰が通話中？セールスキューはどのくらい詰まってる？" 📊 "ウィンバック用のプレビューキャンペーンを作成して、セールススキルを割り当てて、開始して。" 🛠️ "OUTBOUND_AGED キャンペーンを停止して、この 3 件のリードをコールバックリストに追加して。" 📞 "新しいエージェントをオンボーディングして：ユーザーを作成して、レベル 2 で売上スキルを割り当てて。" 🧑💼 "555-867-5309 はうちの DNC リストに入ってる？誰かが発信する前に確認して。" 🚫 " "昨日のコールログレポートを取得して、放棄率をまとめて。" 📈 "完全な IVR を作って：オプション1 はスケジュール、オプション2 は請求、営業時間後はボイスメール。" 🧩

内部では、このサーバーは Five9 の Configuration(管理者) と Statistics(スーパーバイザー)という SOAP Web Services ― Five9 の管理画面を支えてきた API ― と対話し、それらを MCP streamable HTTP 上のクリーンな JSON ツールとして露出します。手組みのエンベロープ、約 60 行の XML パーサー、npm パッケージは一切なし。すべてのツールは実在の Five ドメインに対して動作確認済みです。

✨ 組み込みの Web UI

デプロイすると、Worker は API 以上のものを提供します：

コンソールは、認証情報の確認、各ツールの返り値の調査、キャンペーンのデバッグを最短で行える手段です。AI は不要です。

Related MCP server: five9-mcp

🚀 クイックスタート ― ターミナル不要

無料の Cloudflare アカウントと、API アクセス権を持った Five9 ユーザーが必要です。― 専用の Five9 ユーザーを、AI にやらせたい権限だけに絞って作成してください。個人の管理者ログインを流用しないこと。

1 ― Cloudflare にデプロイ (ブラウザ内でワンクリック)

Cloudflare にサインインして、クリックで進めるだけ。自分の Worker のコピー(必要な KV 名前空間も含む)が作られ、https://five9-mcp.you.workers.dev のような URL が発行されます。

2 — セットアップウィザードを実行 (ブラウザ内)

新しいサーバーの /setup を開きます。Five9 のユーザー名、パスワード、リージョンを入力すると、ウィザードが保存前に Five9 にライブ照合して、アクセスキー を発行します(一度きりの表示なので、パスワードマネージャーに保存してください)。

3 — AI を接続 し(手順は下)、"接続を確認して、キャンペーンを一覧表示して" と頼んでみましょう。 🎉

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 にあり、米国向けドメインでそのまま使えます。

🔌 AI を接続する

Claude を接続(Web 版 & デスクトップ版)

カスタムコネクタは、Free(1 つ)、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. Web 版 ChatGPT で、設定 → Apps & Connectors を開きます(単に Connectors と表示されることもあります)。

2. 詳細設定(Advanced settings)で、開発者モード をオンにします。

3. コネクタのページに戻り、作成 をクリックします。

4. 名前を Five9 にし、MCP サーバー URL を https://<your-worker>.workers.dev/mcp に設定し、認証は OAuth を選びます。

5. 信頼の確認ダイアログを承認して保存します。ChatGPT がこのサーバーの認証ページを開くので、MCP_AUTH_TOKEN を貼り付けて Authorize をクリックします。

6. 新しいチャットで、＋ / ツールメニューを開き、Five9 コネクタを有効にします(開発者モードのコネクタは会話ごとに有効になります)。ChatGPT が各ツール呼び出しの確認を求めます。ダイヤラーを起動できる何かには賢明な設計です。 😄

Classe Code を接続する

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

アクセスキーをそのまま Bearer トークン(・認証は不要)として使えます。Claude Code 内で /mcp を実行すれば確認できます。

その他の 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、リフレッシュ トークン)。

• 同意画面での「ログイン」は、サーバーのアクセスキーであり、その実体は MCP_AUTH_TOKEN です。

• すべてステートレスで、クライアント ID、認可コード、トークンは、HMAC-SHA256 で署名された MCP_AUTH_TOKEN キー付きのブロブです。KV も DurableDK オブジェクトも不要。

• 両方の認証方式が同時に使えます。OAuth で発行されたトークンも、生のアクセスキーを Bearer 認証情報として使うこともできます。

• シークレットをローテーションすれば、すべてをまとめて無効化できます。npx wrangler secret put MCP_AUTH_TOKEN。

🧰 ツールボックス

77 個のツール。🟢 = 読み取り(常に安全)・✏️ = 書き込み(ドメインを変更します。サーバーが AI に「先にユーザーへ確認するように」と指示します)。

69 個の SOAP ツール(ユーザー名/パスワード) + 8 個の OAuth ニュープラットフォーム REST ツール は Consumer Key/Secret — 詳しくは OAuth New Platform APIs へ。

この目玉機能：通話フローを文章で説明すると、AI がそれを設計し、チャットに Mermaid 図 を表示し、動作する IVR スクリプトを配備します。モデルは Five9 の IVR XML を自由に解釈するのではなく、制約付きの JSON フロー・スペック(play / playリメニュー / business-hours [営業時間] / スキルトランスファー / ボイスメール / ハング)を入力し、グラフ検証器がすべての分岐と参照をチェックし、決定論的なコードで検証された XML が生成されます(モジュール配線、プロンプトのエンコーディング、フィールド順は、実際に書き出せたスクリプトから取得)。

推奨：validate → render(人間へ表示！)→ generate prompts プロンプトを作成してアップロード → build 構築 → インバウンド キャンペーンへアタッチ。generate_prompt_audio は Cloudflare Workers AI を そのまま使います。外部 TTS アカウントや APIキーは不要で、プロンプトあたり 1 セント未満の料金が、すでにデプロイ済みの Cloudflare アカウントに請求されます。各キー secret を設定すれば ElevenLabs / OpenAI も同様に使えます。{tts} プロンプト(T のFive の組み込みロボ音声)は何も必要ありません。

これらのツールは、上記のツールが使用する SOAP API ではなく、Five9 の新しい OAuth 2.0 "New Platform" REST API を使用します。これらには API Access Control 認証情報（Consumer Key/Secret）が必要で、SOAP のユーザー名/パスワードではありません — OAuth New Platform APIs を参照してください。

🔐 OAuth New Platform APIs

SOAP ツールに加えて、サーバー from Five9 の新しい OAuth 2.0 New Platform REST APIs（例：Circles、interactions、prompts、domain metadata）を呼び出せます。これらは SOAP のユーザー名/パスワードとは異なる認証情報を使用します：

• API Access Control の Consumer Key と Consumer Secret（Five9 の 管理コンソール → API Access Control で生成。Controlled-Availability 機能です）を用意します。生成には security → applications → Create applications の権限が必要で、アカウントが Five9 Identity Service に移行済みであることも必要です（レガシーの API/Agent/Supervisor ロールを持つユーザーは、それらのロールが削除されるまで移行対象から除外されます）。

• これらを（SOAP の認証情報とは別に）env/secret 変数として設定します:

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 family + scopes によって決まります。all-apis-access は、文字どおりすべてのサービスへのアクセスを許可するわけではなく、書き込みアクセスもサービスごとに判断されます。

複数のクレデンシャル / ファミリー。 各 API Access Control のクレデンシャルは、1つの family（Apigee API Product にマッピングされる）に属し、そのファミリーがキーから呼び出し可能なサービスを決定します。サーバーは 名前付きクレデンシャル をサポートしています: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 には、MCP の instructions フィールドと about ツールを通じて接続中の AI に提供されるテキスト（誰がサーバーを運用しているか、なぜ存在するか、AI がどう振る舞うか。例:「書き込み操作の前に確認」）が入っています。独自のデプロイ環境を説明するように編集してください — 元のオペレーターのコンテキストがサンプルとして同梱されています。

🏗️ アーキテクチャ

ビルドステップも依存関係もありません。src/ 内のプレーンな JS モジュールだけです:

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 の呼び出しのたびに、HTTP Basic 認証で新しい Five9 SOAP 通信を開きます。Statistics API にはさらに setSessionParameters の呼び出しが必要で、get_realtime_stats が呼び出しごとにそれを実行します。

• Five9 のエンドポイントは JAXB で生成されており、子要素の順序を検証します。このサーバーを拡張する場合は、WSDL（https://api.five9.com/wsapi/v13/AdminWebService?wsdl.0、HTTP Basic 認証）を取得し、<xs:sequence> の順序を厳密に合わせてください。basicImportSettings のような基本型の要素が、拡張型の要素より前に来るものも含みます。

• addToListCsv は、WSDL では minOccurs="0" とされているにもかかわらず、cleanListBeforeUpdate、crmAddMode、crmUpdateMode、listAddMode が必須です。

• リスト/CRM インポートは非同期です。呼び出しは即座にインポート ID を返し、結果は get_import_result をポーリングして確認します。

• コンタクトレコードの値はラップされて返されます（<values><data>…</data></values>）。また、1要素の配列を期待する場面で単一のオブジェクトが返るレスポンスもいくつかあります。five9.js の toArray() がこれを正規化します。

• レポートの時間条件は、JAXB のアルファベット順により、<end> が <start> の前に来ます。

• IVR の xmlDefinition はビジュアルデザイナーが永続化する形式です。モジュールは GUID（ascendants / singleDescendant / branches）で配線され、インライン TTS テキストは gzip+base64 の speakElement ドキュメントとして保存され、営業時間チェックは __DAY__（SUN=1..SAT=7）と __TIME__（深夜0時からの分数）のシステム変数を比較します。ivr.js がこのすべてをカプセル化しています。

• getPrompts はプロンプト ID を返しません（name と type のみ）。IVR XML 内のファイルプロンプト参照は、id 0 + プロンプト名で受け付けられ、サーバー側で正規化されます。プッシュされたスクリプトは、サーバーが付与した domainId が追加されて戻ってきます。

🛡️ セキュリティ

• Five9 のクレデンシャルは、Cloudflare アカウント内にのみ存在します。Worker secrets、あるいはウィザードの場合は暗号化された Workers KV namespace として保持されます。どのツールもそれらを返すことはなく、Wrangler の secret は常に KV よりも優先されます。

• セットアップウィザードは、新規で未設定のサーバーでのみ開きます。デプロイ直後に実行してください。一度設定すると、変更には現在のアクセスキーが必要で、env 管理のサーバーはウィザードからの変更を一切拒否します。

• 必ずセットアップを完了するか MCP_AUTH_TOKEN を設定してください。 アクセスキーなしの未設定サーバーは開放状態で動作し、URL を知った誰にでもコンタクトセンターを操作されてしまいます。

• 書き込みツール（上記の ✏️）はドメインを変更します。Five9 API ユーザーのロールは、AI に実際に行わせたい範囲に絞ってください — Five9 の権限設定が本当のセキュリティ境界です。

• manage_dnc remove と delete_list は特に注意が必要です。about の指示では、使用前に確認するよう AI に求めています。

• コンソールはアクセスキーをブラウザの localStorage にのみ保存し、呼び出しは自分の Worker に対して同一オリジンで行われます。

💻 開発

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

ローカル用の秘密情報を .dev.vars（gitignore 済み）に入れます:

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 スニペットで CLI からスモークテストすることもできます。

🤝 コントリビューション

PR 歓迎です。Five9 Config API には約 180 のオペレーションがありますが、このサーバーはその中で最も便利なもの約 69 をラップしています。five9.js + tools.js のパターンは拡張しやすいです（先に SOAP のメモを読んで、WSDL との戦いを避けてください）。依存関係ゼロの制約は守ってください。

📄 ライセンス

MIT · Ryan Shatzkamer がこの作った