voicent-mcp

Voicent MCP サーバー

AI エージェントがオンプレミスの Voicent Gateway を利用して、電話やテキストメッセージの送信、キャンペーンの実行、結果の確認、CRM レコードの読み取りと更新を行えるようにします。

これはフェーズ 1 で、Simple Gateway API、Campaign API、CRM API を対象としています。CRM の検索など、製品の変更が必要な機能はフェーズ 2 で対応します。

Voicent Gateway 10.10.3 以降が必要です。 古いバージョンでは、音声通話が失敗し、リクエストの保存時に中国語のテキストが失われ、顧客フィールドのアポストロフィが誤って保存されます。

Voicent ライセンス： 製品の Workflow ライセンスと Enterprise Edition が必要です。

ツール

個別の通話、テキストメッセージ、CRM のツールはデフォルトで有効で、キャンペーンは無効です。無効になっているツールは、エージェントから利用できません。

設定	ツール
常に有効	call_status、campaign_status、import_status
VOICENT_ALLOW_CALLS=0 でない限り有効	call_text、call_audio、call_ivr、send_sms、call_remove
VOICENT_ALLOW_CRM=0 でない限り有効	crm_get_field、crm_add_or_update、crm_set_field、crm_add_note、crm_schedule_callback、crm_notify_agent
VOICENT_ALLOW_CAMPAIGNS=1 でない限り無効	campaign_import_list、campaign_upload_audio、campaign_export、campaign_run_autodialer、campaign_run_text、campaign_run_email

まだ含まれていない機能：予測ダイヤラーキャンペーン、スケジュール設定または繰り返し実行するキャンペーン、リモートゲートウェイへのファイルのアップロード、CRM レコードの検索、一覧表示、削除。検索機能がないため、エージェントはレコードの ID、または顧客の電話番号かメールアドレスを知っている必要があります。

設定

変数	目的
VOICENT_GATEWAY_URL	ゲートウェイのアドレス。デフォルト：http://localhost:8155
VOICENT_ALLOW_CALLS	0 にすると、個別の通話とテキストメッセージを無効にします。デフォルト：有効
VOICENT_ALLOWED_NUMBERS	カンマ区切りの番号に、個別の通話とテキストメッセージを制限します。デフォルト：すべての番号
VOICENT_ALLOW_CRM	0 にすると、CRM ツールを無効にします。デフォルト：有効
VOICENT_ALLOW_CAMPAIGNS	1 にすると、キャンペーンとリストのインポートを有効にします
VOICENT_FILE_ROOT	音声、インポート、エクスポートの各ファイルをこのフォルダー内に限定します。この値が設定されていない場合、ファイルツールは実行できません
VOICENT_PASSWORD	ゲートウェイがこのマシン上にない場合に必要な、ゲートウェイの Remote Connect Password
VOICENT_USERNAME	VOICENT_PASSWORD が Remote Connect Password ではなくユーザーのパスワードの場合に使うログイン名。クラウドサービスモードでは、アカウント所有者はメールアドレスではなく admin を使用します
VOICENT_ACCOUNT_ID	アカウント ID（cc_card_id）。クラウドサービスモードのゲートウェイでのみ必要です
VOICENT_TIMEOUT_MS	リクエストのタイムアウト。デフォルト：30000

ファイルパスはゲートウェイによって読み取られるため、このサーバーがゲートウェイマシン上で実行されている場合にのみファイルツールを使用できます。

安全性

• デフォルトでは、エージェントは任意の数の電話番号に発信またはテキストメッセージを送信できます。 たとえばテスト中に制限するには、VOICENT_ALLOWED_NUMBERS を設定します。発信とテキストメッセージを無効にするには、VOICENT_ALLOW_CALLS=0 を設定します。
• VOICENT_ALLOWED_NUMBERS はキャンペーンには適用されません。 キャンペーンはリストに登録されている全員に連絡するため、VOICENT_ALLOW_CAMPAIGNS を有効にするのは、それが許容される場合に限ってください。
• リストのインポートには、CRM ツールのような制限はありません。 campaign_import_list は、VOICENT_FILE_ROOT 内のファイルから、DO_NOT_CALL の解除も含め、一致する連絡先の任意の列を更新できます。自分でインポートするファイルだけをここに置いてください。
• CRM の読み取りでは顧客レコードが AI プロバイダーに送信され、CRM の書き込みではレコードが変更されます。 CRM ツールを無効にするには、VOICENT_ALLOW_CRM=0 を設定します。
• CRM ツールの制限： 読み取りまたは変更が可能なのは既知のフィールドのみです。エージェントは DO_NOT_CALL と DO_NOT_EMAIL を yes に設定できますが、これらを解除できるのは人だけです。crm_add_or_update は、overwrite が true でない限り、空の値だけを入力します。通知はプレーンテキストです。
• ゲートウェイ自体を保護してください。 これらの制限はこのサーバーにのみ適用されます。ゲートウェイは localhost から接続でき、ほかの場所から接続するには Remote Connect Password が必要です。リモートログインから IVR アプリをデプロイしたり SQL を実行したりできるため、Voicent App > Setup > Options > Control で独自のパスワードを設定してください。 信頼できないネットワークにポートを公開しないでください。パスワードチェックがないコールフローページもあります。
• リクエストは固定されたフィールド一式から構築されます。サーバーが sql やデータベースフィールド、startvxml や starturl、または ignorednc（Do Not Call を回避するためのもの）を送信することはありません。
• 電話番号には厳格な形式の単一の番号を指定する必要があり、これによりゲートウェイの特殊な値 dbquery、dialer、vcenter はブロックされます。

実行

Deno が必要です。

deno task test      # tests against a fake gateway; nothing is dialed
deno task start     # run from source
deno task compile   # build dist/voicent-mcp.exe, which runs without Deno

Claude Code への接続

.mcp.json に次の内容を追加します。

{
  "mcpServers": {
    "voicent": {
      "command": "C:\\voicent-mcp\\voicent-mcp.exe",
      "env": {
        "VOICENT_GATEWAY_URL": "http://localhost:8155"
      }
    }
  }
}

接続する前に： この設定では、エージェントは任意の番号に発信またはテキストメッセージを送信でき、顧客レコードを読み取って AI プロバイダーに送信し、レコードを変更できます。変更するには、env に設定を追加してください。

目的	追加する設定
発信とテキストメッセージを特定の番号に制限する	"VOICENT_ALLOWED_NUMBERS": "650-555-0100,650-555-0101"
発信とテキストメッセージを無効にする	"VOICENT_ALLOW_CALLS": "0"
CRM ツールを無効にする	"VOICENT_ALLOW_CRM": "0"
キャンペーンを有効にする	"VOICENT_ALLOW_CAMPAIGNS": "1"
音声、インポート、エクスポート用のファイルを許可する	"VOICENT_FILE_ROOT": "C:\\voicent-files"

サーバーは起動するたびに、ログにこれらの警告を再度出力します。

開発者向けドキュメントとの相違点

サーバーは、ゲートウェイが実際に読み取る内容を送信します。以下の点で開発者向けドキュメントと異なります。

• メールキャンペーンでは、インラインコンテンツを msginfo（件名）と msgbody として渡し、msgtype は指定しません。ドキュメントには msgtype=file と msgfilepath が記載されていますが、ゲートウェイはこれらを読み取りません。
• call_ivr は startapp フィールドを使用します。
• すべてのリクエストで、パスワードは agent_password として送信され、ユーザーログインの場合は agent_username も送信されます。ドキュメントでは Remote Connect Password に passwd を使用していますが、ゲートウェイはどちらの名前でも受け付けます。

既知の問題

• 電話番号やメールアドレスで検索すると、重複がある場合に誤ったレコードが一致することがあります。 レコード ID がわかる場合は、それを使用してください。

• call_ivr では、アプリがアウトバウンドかどうかを確認できません。 デプロイされていない名前は拒否されます。アウトバウンドアプリのみを使用してください。

• 留守番電話メッセージが設定されていない IVR アプリは、留守番電話につながったときに failed で終了することがあります。IVR Studio でアプリにメッセージを追加してください。

ライセンス

このサーバーは MIT License の下で提供されています。LICENSE を参照してください。接続先の Voicent ソフトウェアは別途ライセンスされています。