☎️ 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サービスと通信します。これらはFive9の管理画面を今も動かしているAPIであり、MCPストリーミングHTTP経由でクリーンなJSONツールとして公開されます。手書きのエンベロープ、約60行のXMLパーサー、npmパッケージは一切なし。すべてのツールは実稼働のFive9ドメインに対してテスト済みです。

✨ 内蔵Web UI

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

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

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

無料の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という名前を付け、/mcpパスを含むサーバーURLを貼り付けます： https://<your-worker>.workers.dev/mcp

4. 追加、次に接続をクリックします。Claudeはこのサーバーの内蔵OAuthを自動検出し、認証ページを開きます。

5. 🔐 five9-mcp画面で、MCP_AUTH_TOKENをアクセスキーとして貼り付け、認可をクリックします。

6. 任意のチャットで、検索とツール（＋）メニューを開き、Five9コネクタがオンになっていることを確認します。

Team/Enterpriseの場合： 最初にOwnerが組織設定 → コネクタでコネクタを追加し、メンバーは自分の設定で接続をクリックして認可します。

ChatGPTに接続

カスタムMCPコネクタには開発者モードが必要です（Plus/Pro。Business/Enterpriseでは管理者がカスタムコネクタを許可する必要があります）。

1. ウェブの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ツール（コンシューマーキー/シークレット — OAuth New Platform APIsを参照）。

目玉機能：コールフローを1段落で説明すると、AIが設計し、チャットにMermaidダイアグラムを表示し、動作するIVRスクリプトをデプロイします。モデルはFive9のIVR XMLを自由に書いたりはしません。制約付きのJSONフロースペック（再生 / メニュー / 営業時間 / スキルトランスファー / ボイスメール / 切断）を埋め、グラフバリデーターがすべての分岐と参照をチェックし、決定論的なコードがデザイナー準拠のXMLを生成します（モジュール配線、プロンプトエンコーディング、フィールド順序はすべて実際にエクスポートされたスクリプトから導出）。

推奨フロー：検証 → レンダリング（人間に見せる！）→ プロンプト生成 → ビルド → インバウンドキャンペーンにアタッチ。generate_prompt_audioはCloudflare Workers AI上でそのまま動作します：外部TTSアカウント不要、APIキー不要、プロンプト1つあたり1円未満で、すでにデプロイしたCloudflareアカウントに請求されます。キーシークレットを設定すればElevenLabs/OpenAIも使用でき、{tts}プロンプト（Five9内蔵のロボット音声）なら何も必要ありません。

これらのツールは、Five9 のモダンな OAuth 2.0 "New Platform" REST APIs を使用します。上記のツールが使用する SOAP API ではありません。API Access Control 資格情報（Consumer Key/Secret）が必要であり、SOAP のユーザー名/パスワードは 不要 です — OAuth New Platform APIs を参照。

🔐 OAuth New Platform APIs

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

• API Access Control の Consumer Key と Consumer Secret。Five9 管理コンソール → API Access Control (限定提供機能) で生成します。生成には security → applications → Create applications 権限が必要で、アカウントが Five9 Identity Service に移行済みである必要があります (従来の API/エージェント/スーパーバイザーの役割を持つユーザーは、それらの役割が削除されるまで移行対象から除外されます)。

• これらを 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 プロダクトにマッピング) に属し、そのファミリーがキーが呼び出せるサービスを決定します。サーバーは 名前付き認証情報 をサポートしています: 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() がこれを正規化します。

• レポートの時間条件の順序は <end> が <start> の 前 です (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 によって構築