☎️ 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ストリーミング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.あなたの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、認証コード、トークンはHMAC-SHA256署名されたブロブで、MCP_AUTH_TOKENをキーとしています。KVもDurable Objectsも不要。

• 両方の認証パスが同時に機能します：OAuthで発行されたトークンと、ベアラークレデンシャルとしての生のキーの両方。

• シークレットをローテーションすることで一度にすべてを取り消します：npx wrangler secret put MCP_AUTH_TOKEN

🧰 ツールボックス

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

69のSOAPツール（ユーザー名/パスワード）＋8つのOAuth New Platform RESTツール（コンシューマーキー/シークレット — OAuth New Platform APIsを参照）。

最大の見せ技：コールフローを一文で説明すると、AIがそれを設計し、チャット内にMermaidダイアグラムを表示し、動作するIVRスクリプトをデプロイします。モデルはFive9のIVR XMLを自由に生成しません。制約付きのJSONフロースペック（プレイ/メニュー/営業時間/スキル転送/ボイスメール/切断）を埋め、グラフバリデーターがすべての分岐と参照をチェックし、決定論的なコードがデザイナーが生成するXML（モジュール配線、プロンプトエンコーディング、フィールド順序はすべて実際のエクスポートスクリプトから派生）を出力します。

推奨フロー：検証 → レンダリング（人間に見せる！） → プロンプト生成 → ビルド → インバウンドキャンペーンにアタッチ。generate_prompt_audioはCloudflare Workers AIをそのまま使用します。外部のTTSアカウントもAPIキーも不要で、プロンプトあたりのコストはすでにデプロイしたCloudflareアカウントに請求されるわずかな金額です。ElevenLabs/OpenAIも、キーシークレットを設定すれば使用可能です。また、{tts}プロンプト（Five9の組み込みロボット音声）は何も必要ありません。

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

🔐 OAuth New Platform API

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

• API アクセス制御の Consumer Key と Consumer Secret（Five9 の 管理コンソール → API アクセス制御 で生成します。これは限定提供機能です）。生成するには 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 アクセス制御の認証情報は 1 つの ファミリー（Apigee API プロダクトにマッピング）に属し、そのファミリーがキーが呼び出せるサービスを決定します。サーバーは 名前付き認証情報 をサポートしています：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 がどのように振る舞うべきか（例：「書き込み操作の前に確認」）など。自身のデプロイメントを説明するように編集してください — 初期状態では元のオペレーターのコンテキストがサンプルとして含まれています。

🏗️ アーキテクチャ

ビルドステップは不要、依存関係もなし — プレーンな JS モジュールを 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

リクエストはステートレスです：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 が必要です。

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

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

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

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

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

🛡️ セキュリティ

• Five9 の認証情報は、Cloudflare アカウント内にのみ存在します — Worker シークレットとして、または（ウィザードパスでは）Workers KV 名前空間内に保存され、暗号化されて保存されます。どのツールもこれらを返すことはなく、Wrangler シークレットは常に KV よりも優先されます。

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

• 必ずセットアップを完了するか、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