☎️ five9-mcp

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

オープンソースのMCPサーバー。Claude、ChatGPT、または任意のMCPクライアントをFive9クラウドコンタクトセンターに接続します — 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ストリーミングHTTP上のクリーンなJSONツールとして公開します。手書きのエンベロープ、約60行のXMLパーサー、npmパッケージなし。すべてのツールは実在のFive9ドメインに対してテスト済みです。

✨ 組み込みWeb UI

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

コンソールは、認証情報の確認、各ツールの戻り値の調査、キャンペーンのデバッグに最速の方法です — AIは不要です。

Related MCP server: five9-mcp

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

無料のCloudflareアカウントと、APIアクセス権を持つFive9ユーザーが必要です — 専用のFive9 APIユーザーを作成し、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で、設定 → アプリとコネクタ（単にコネクタと表示されることもあります）を開きます。

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

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

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

5. 信頼プロンプトを確認して保存します。ChatGPTがこのサーバーの認証ページを開きます — MCP_AUTH_TOKEN を貼り付けて 承認 をクリックします。

6. 新しいチャットで、＋ / ツールメニューを開き、Five9 コネクタを有効にします（開発者モードのコネクタは会話ごとに有効化されます）。ChatGPTは各ツール呼び出しの確認を求めます — ダイヤラーを起動できるものには賢明な対応です。😄

Claude Codeに接続

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

生のアクセスキーはベアラートークンとしてそのまま機能します — OAuthの手順は不要です。Claude Code内で /mcp を実行して確認してください。

その他のMCPクライアント

MCP ストリーミングHTTP に対応するものなら何でも動作します — OAuthフローを完了するか、アクセスキーをベアラートークンとして送信してください：

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、認可コード、トークンは MCP_AUTH_TOKEN をキーとするHMAC-SHA256署名付きブロブです。KVもDurable Objectsも不要。

• 両方の認証パスが同時に機能します：OAuth発行トークン および ベアラ資格情報としての生キー。

• シークレットをローテーションすれば一度にすべてを失効させられます：npx wrangler secret put MCP_AUTH_TOKEN。

🧰 ツールボックス

77個のツール。 🟢 = 読み取り（常に安全）· ✏️ = 書き込み（ドメインを変更 — サーバーはAIに事前確認を指示します）

69個のSOAPツール（ユーザー名/パスワード）+ 8個のOAuth New Platform RESTツール（Consumer Key/Secret — OAuth New Platform APIs を参照）。

目玉機能：通話フローを一文で説明すると、AIが設計し、チャットにMermaid図を表示し、動作するIVRスクリプトをデプロイします。モデルはFive9のIVR XMLを自由に書くことはありません：制約付きJSONフロースペック（play / menu / business-hours / skill transfer / voicemail / hangup）を埋め、グラフバリデーターがすべての分岐と参照をチェックし、決定的なコードがデザイナー形式のXML（モジュール配線、プロンプトエンコーディング、フィールド順序はすべて実際のエクスポート済みスクリプトから導出）を生成します。

推奨フロー：validate → render（人間に見せる！）→ generate prompts → build → インバウンドキャンペーンにアタッチ。generate_prompt_audio はCloudflare Workers AIでそのまま動作します：外部TTSアカウント不要、APIキー不要、プロンプト1件あたり数分の1セントが、すでにデプロイ先のCloudflareアカウントに請求されます。ElevenLabs/OpenAIもキーシークレットを設定すれば動作し、{tts} プロンプト（Five9の組み込みロボット音声）は何も必要ありません。

These tools speak Five9's modern OAuth 2.0 "New Platform" REST APIs, not the SOAP APIs the tools above use. They require an API Access Control credential (Consumer Key/Secret), not the SOAP username/password — see OAuth New Platform APIs.

🔐 OAuth New Platform APIs

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

• API Access Control の Consumer Key と Consumer Secret。Five9 の Admin Console → API Access Control(Controlled-Availability 機能)で生成します。生成には security → applications → Create applications 権限が必要で、アカウントが Five9 Identity Service に移行済みである必要があります(従来の API/Agent/Supervisor ロールを持つユーザーは、それらのロールが削除されるまで移行対象から除外されます)。

• これらを env/secret 変数として設定します(すべて SOAP 認証情報とは別):

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 ファミリー + スコープ によって決まります。all-apis-access は文字どおりすべてのサービスを許可するわけではなく、書き込みアクセスはサービスごとに付与されます。

複数の認証情報 / ファミリー。 各 API Access Control 認証情報は 1 つの ファミリー(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 のシーケンスに対して子要素の順序を検証します。このサーバーを拡張する場合は、WSDL(https://api.five9.com/wsadmin/v13/AdminWebService?wsdl、HTTP Basic 認証)を取得し、<xs:sequence> の順序に正確に合わせてください — basicImportSettings のような基本型も含みます。その要素は拡張型の要素より前に来ます。

• addToListCsv は、WSDL ではそれらのほとんどが minOccurs="0" とマークされているにもかかわらず、cleanListBeforeUpdate、crmAddMode、crmUpdateMode、listAddMode を必要とします。

• List/CRM インポートは非同期です。呼び出しはすぐにインポート識別子を返すため、結果を取得するには get_import_result をポーリングします。

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

• レポートの時間条件の順序は、<start> の前に <end> です(JAXB のアルファベット順)。

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

• getPrompts はプロンプト ID を返しません(名前 + タイプのみ)。IVR XML 内のファイルプロンプト参照は、id 0 + プロンプトの名前で受け付けられ、サーバー側で正規化されます。プッシュされたスクリプトは、サーバーが付与した domainId が追加された状態でラウンドトリップします。

🛡️ セキュリティ

• Five9 の認証情報は Cloudflare アカウント内にのみ存在します。Worker シークレットとして、または(ウィザードのパスでは)Workers KV 名前空間に保存時暗号化されて格納されます。どのツールもこれらを返すことはなく、Wrangler シークレットは常に 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 によって構築