CallRail MCP

callrail-mcp

Model Context Protocol サーバーです。CallRail REST API v3 に対応しています。Claude Code、Claude Desktop、Cursor、その他の MCP クライアントを接続すれば、通話トラッキングについて平易な英語で質問できます。

私は Steve Japalucci です。Pittsburgh Digital Marketing Agency (PGHDMA) を運営しており、自分のクライアント業務のためにこれを作りました。管理しているすべてのクライアントについて、CallRail はトラッキング番号ごと、分ごとに課金します。「今月、どのクライアントが通話時間を最も消費しているか」といった質問に答えるため、レポートをクリックして回るのにうんざりしていました。今は Claude に尋ねています。

MCP Python SDK の両方のメジャーバージョン（1.x と 2.x）で動作します。

活用例

毎週、次のような質問をしています。

レポート

• 「Alan Construction の先週の通話を、流入元別にまとめて取得して」
• 「今月の不在着信をすべて表示して」
• 「過去90日間に、すべてのクライアントで412-555-1234からの通話があったか調べて」
• 「通話 CAL019abc... の文字起こしを取得して」

代理店のコスト配賦

• 「CallRail の請求額が174ドルなのはなぜ？クライアント別に内訳を出して」
• 「今期、最も通話時間を使っているクライアントは？」

コンバージョンのデバッグ

• 「この通話が Google Ads でコンバージョンにならなかったのはなぜ？CAL019...」
• 「この58秒の通話は、Google Ads のコンバージョンとしてカウントできますか？」

リード管理

• 「この人のこれまでのすべての行動を表示して。通話、フォーム、テキストを含めて」
• 「この SMS スレッドに有望なリードのタグを付けて、メモを追加して」

タグとトラッカーの管理

• 「この通話に「lead」のタグを付けて、メモを追加して」
• 「Renaissance 向けに、エリアコード412の新しい Google Ads 通話アセット用トラッカーを設定して」（confirm_billing=True が必要です。月額約3ドルかかります）

インストール

# Recommended: pipx for an isolated CLI install
pipx install callrail-mcp

# Or with pip
pip install callrail-mcp

ソースからインストールする場合（未リリースの最新バージョン）：

pipx install git+https://github.com/pghdma/callrail-mcp.git

認証

CallRail アカウントの Settings > API Keys で API キーを取得してください。API キーの作成にはアカウント管理者の権限が必要です。

次のいずれかの方法で指定してください。

方法1：環境変数（ほとんどの設定で推奨）

export CALLRAIL_API_KEY="your_key_here"

方法2：キーファイル

mkdir -p ~/.config/callrail
echo "your_key_here" > ~/.config/callrail/api-key.txt
chmod 600 ~/.config/callrail/api-key.txt

または、CALLRAIL_API_KEY_FILE=/path/to/key.txt で上書きできます。

オプション：アカウントを固定する

各ツールはプロセスごとに GET /a.json を1回実行してアカウント ID を取得し、キャッシュします。この照会をスキップする場合、またはキーから複数のアカウントにアクセスできるときに1つのアカウントに固定する場合は、CALLRAIL_ACCOUNT_ID を設定してください。

MCP クライアントの設定

Claude Code / Claude Desktop（~/.claude.json または claude_desktop_config.json）

{
  "mcpServers": {
    "callrail": {
      "command": "callrail-mcp",
      "env": {
        "CALLRAIL_API_KEY": "your_key_here"
      }
    }
  }
}

pipx 経由でインストールした場合、callrail-mcp は自動的に PATH 上に配置されます。それ以外の場合は、command に実行ファイルのフルパスを指定してください。

Cursor およびその他のクライアント

このサーバーは標準の MCP stdio に対応しています。stdio MCP サーバーをサポートするクライアントであれば、コマンドとして callrail-mcp を実行するだけで使用できます。

利用可能なツール

合計57個のツールで、CallRail REST API v3 の機能の約95％をカバーしています。読み取りツール、書き込みツール、トラッカーの設定、代理店全体の集計、アカウント管理、通知、インテグレーションの検出、発信通話、オフラインリードのバックフィル、リードとチャネル横断のタイムライン、SMS スレッドでのリード管理、サーバー側の分析に対応しています。

読み取りツール

ツール	目的
list_accounts	アクセス可能な CallRail アカウントを一覧表示します。fields="numeric_id" を指定すると、CallRail の URL に表示される番号が追加されます
list_companies	アカウント配下の会社（クライアント）を一覧表示します。status="active"、search、fields（例：verified_caller_ids）、page を指定できます
list_trackers	トラッキング用電話番号とそのソースマッピングを一覧表示します。status="active"、type、search、fields を指定できます
get_tracker	1 件のトラッカーの詳細を取得します
list_calls	ページ分割された通話一覧です。会社、期間、answer_status、direction、device、call_type、lead_status、tracker_id、tags、フリーテキストの search で絞り込めます。また、sort／order と IANA の time_zone を指定できます
get_call	特定の通話の詳細を取得します
call_summary	期間内の集計統計（合計、人が応答した通話、ボイスメール、不在着信、ソース別、通話時間）を取得します
list_form_submissions	CallRail Form Tracking の送信内容です。lead_status、tags、person_lead で絞り込めます。submitted_at または form_url で並べ替えられます
list_text_messages	SMS の会話を取得します
list_users	ページ分割されたアカウントユーザー一覧です。company_id、名前やメールアドレスの search で絞り込めます。email または created_at で並べ替えられます
get_call_recording	録音が有効な場合、録音 URL を取得します。CallRail によると、リンクは少なくとも 24 時間有効です。HIPAA アカウントでは、約 24 時間で期限切れになる一時 URL が提供されます
get_call_transcript	フィールド選択により、トランスクリプトに加えて conversational_transcript、call_summary、call_highlights、keywords_spotted、sentiment、speaker_percent を取得します（2026-05-21 以降は Premium Conversation Intelligence が必要です）
search_calls_by_number	期間内の電話番号で通話を検索します（サーバー側で search により絞り込んだ後、完全一致で照合します）
list_tags	アカウント内、または 1 つの会社に絞ったタグを一覧表示します。status と tag_level で絞り込めます

書き込みツール

ツール	目的
update_call	メモ、タグ、スパムフラグ、顧客名、リードステータスを更新します
add_call_tags / remove_call_tags	タグを追加または削除します（既存のタグは保持されます）
update_form_submission	メモ、タグ（置き換え、または append_tags=True で追加）、value（CallRail のドキュメントに記載された通貨文字列として送信）、リードステータスを更新します。フォーム送信にはスパムフラグがありません
create_tag / update_tag / delete_tag	会社レベルおよびアカウントレベル（tag_level="account"）のタグに対する CRUD 操作を行います。update_tag ではタグの無効化や再有効化もできます

トラッカーのプロビジョニング

ツール	目的
create_tracker	新しいトラッキング番号をプロビジョニングします。誤操作によるプロビジョニングを防ぐ安全策として、confirm_billing=True が必須です。ソーストラッカーと、4～50 件の番号を含むセッション（DNI）プールに対応しています。ソース固有のフィールドはタイプごとに検証されます（search には search_engine と search_type、ランディングタイプには landing、web_referrer には referrer）。さらに、swap_targets と campaign_name に対応しています
update_tracker	名前、宛先、ウィスパー、挨拶（テキストまたは録音 URL）、録音フラグ、SMS、スワップターゲット、キャンペーン名など、変更可能な設定を更新します。現在のコールフローを読み込み、変更内容を反映します。また、高度な（IVR）フローの上書きは拒否します
delete_tracker	トラッカーをソフト削除します（電話番号を解放し、履歴は保持します）

アカウント管理

ツール	用途
get_company / create_company / update_company / delete_company	会社（クライアント）の完全な CRUD。CallRail は会社単位ではなく電話番号単位で課金するため、無料です。ソフトデリート方式です。機能の切り替えは、ドキュメントに記載された PUT フィールドを通じて行います（POST で受け付けるのは名前とタイムゾーンのみのため、create_company の直後も同様です）。lead_scoring_enabled は API では読み取り専用です。また、廃止予定の効果のない切り替え項目は、警告とともに除外されます
get_user / create_user / update_user / delete_user	ユーザーの完全な CRUD。create_user はメールで招待します。ロールは admin、manager、reporting です。API ではユーザーのロールやメールアドレスを変更できないため、update_user で変更できるのは名前と会社へのアクセス権のみです
get_tag	単一タグの詳細
get_form_submission	単一フォーム送信の詳細
get_text_message	すべてのメッセージを含む単一 SMS 会話
create_form_submission	フォーム送信を手動で作成します（来店、紙のフォーム、またはオフラインのリードを遡及登録）。form_url と form_data が必要です。アトリビューションには session_id またはリファラーの 3 項目を使用します。メモ、タグ、価値、リードステータスは後続の更新で適用されます

通知とインテグレーション

ツール	用途
list_notifications / create_notification / update_notification / delete_notification	ユーザーごとのアラートルールの完全な CRUD（どの通話、テキスト、フォームのイベントで誰に通知するか）
list_integrations(company_id) / get_integration	会社に紐付けられた GMB、Google Ads、Facebook、Slack、Webhook のインテグレーションを確認します。CallRail は Webhook をインテグレーションの種類として扱うため、Webhook の確認にも使用できます

発信

ツール	用途
create_outbound_call	発信します。CallRail はまず business_phone_number に発信し、次に customer_phone_number へ接続します。発信者番号には caller_id が表示されます。実際の電話番号に発信し、通話料金が発生し、法的な影響も伴うため、安全対策として confirm_dialing=True が必須です。米国とカナダのみ対応しています。任意の agent_id を指定すると、通話をユーザーに割り当てます

リードとサーバーサイド分析

ツール	用途
list_leads / get_lead_timeline	CallRail の重複排除済みの人物レコード（created_at、name、email でソート可能）と、各リードの全チャネルにわたる履歴（通話、フォーム、テキスト）および初回・最終タッチのアトリビューション
list_sms_threads / get_sms_thread / update_sms_thread	SMS スレッドでのリード管理。通話と同様に、テキストメッセージのリードにタグやメモを付け、見込み状況を判定できます。スレッドは日付範囲で絞り込み、電話番号、名前、タグで検索できます
call_stats	/calls/summary.json によるサーバーサイドの通話集計。すべての通話をページネーションで取得する代わりに、1 回のリクエストで会社、company_id、ソース、キーワード、キャンペーン、リファラー、landing_page、last_requested_page ごとにグループ化できます。list_calls と同じサーバーサイドフィルター（answer_status、direction、device、lead_status、first_time_callers、通話時間の範囲、tags、tracker_ids、search、time_zone）に対応しています
call_timeseries	通話量の推移を示す時系列データ。interval（hour、day、week、month、year）と call_stats と同じフィルターに対応しており、送信前に CallRail の 200 データポイントの上限を確認します
form_stats	サーバーサイドのフォーム送信数の集計。group_by（source、keywords、campaign、referrer、landing_page、form_name、company）、fields（total_forms、first_forms、leads）、lead_status、tags に対応しています
get_call_page_views	通話の背後にある訪問者のページ閲覧経路。コンバージョンのデバッグには call_eligibility_check と組み合わせます

代理店の集計

ツール	目的
usage_summary	サイクルごとの会社別コスト配分の内訳です。使用時間、稼働中の番号、推定コストの割合を、コストへの影響が大きい順に表示します。「どのクライアントが CallRail の予算を最も消費しているか」に答えます
call_eligibility_check	特定の通話が Google Ads のコンバージョンとして認定されるかを監査します。gclid の有無、応答状況、通話時間が Google のしきい値（デフォルトは 60 秒）を満たすかどうか、発信元を確認します
compare_periods	現在の N 日間と直前の N 日間を比較します。会社ごとの通話時間と通話件数の差分、および最も大きく変動した項目を表示します
bulk_update_calls	フィルターに一致するすべての通話に、1 件の更新（タグ、メモ、lead_status、スパム）を適用します。デフォルトは dry_run=True で、上限は 500 件です
spam_detector	短い通話時間、未応答、同じ発信者の繰り返しパターンなどから、スパムの可能性が高い通話をヒューリスティックに検出します。任意の auto_tag=True を指定すると auto_detected_spam タグが追加されます。デフォルトの GET から通話が除外される spam=True は意図的に設定しません

すべてのツールで account_id は任意です。省略すると、最初にアクセス可能なアカウントが自動的に解決され、プロセス内でキャッシュされます。アカウントを固定して検索を省略するには、CALLRAIL_ACCOUNT_ID を設定してください。ほとんどのツールでは company_id を指定して、単一のクライアントに絞り込めます。

通話のフィルタリングについて

CallRail の GET /calls.json は answer_status（answered、missed、voicemail）を受け付けますが、answered や source のパラメーターはありません。このサーバーの以前のバージョンでは両方のパラメーターを転送していましたが、CallRail はそれらを黙って無視していたため、結果はフィルター済みに見えても、実際には絞り込まれていませんでした。v1.2.0 でこれを修正しました。

• answer_status は文書化されたフィルターで、サーバー側で適用されます。
• answered は非推奨のエイリアスとして引き続き使用でき、answer_status に変換されます。
• source はクライアント側で適用され、レスポンスには、何が一致したかを正確に示す source_filter ブロックが含まれます。発信元別の内訳には、call_stats(group_by="source") の使用を推奨します。

CallRail について、ほかにも把握しておくべき点が 2 つあります。

• CallRail 側では、ボイスメールも応答済みとしてカウントされます。システムが電話に応答するためです。v1.3.0 以降、call_summary、spam_detector、call_eligibility_check、bulk_update_calls では、人が応答した場合（answered であり、かつ voicemail ではない場合）にのみ応答済みとして扱い、ボイスメールは別途報告します。answer_status=missed にはボイスメールも含まれます。
• 日付の範囲を指定しない場合、CallRail の recent 範囲が使われます。これは今日を含む過去 7 日間であり、全期間ではありません。期間を指定できるツールでは IANA の time_zone を受け付け、日付の境界がクライアントのレポート用タイムゾーンと一致します。また、usage_summary と compare_periods はアカウントのタイムゾーンを自動的に転送します。通信レコードの保持期間は 25 か月のため、それを超える期間を指定すると、より狭い範囲を指定するよう求めるエラーが返されます。

すべての入力は厳密に検証されます。電話番号の形式、市外局番（^\d{3}$）、セッションプールのサイズ（CallRail の範囲は 4～50）、名前、ウィスパーと挨拶文の長さの上限、12 種類の値を持つ発信元タイプの列挙型が対象です。

詳細なフィールド選択

CallRail API がデフォルトで返すペイロードは最小限です。fields パラメーターを使うと、list_calls、get_call、list_form_submissions で追加のフィールドを指定できます。

fields=company_name,source_name,keywords,landing_page_url,device_type,first_call,value,tags,note,gclid,fbclid,utm_source,utm_medium,utm_campaign,utm_content,utm_term,referrer_domain

会話インテリジェンスとアトリビューションのフィールドも、名前で指定できます。lead_status、sentiment、call_summary、call_highlights、keywords_spotted、transcription、conversational_transcript、speaker_percent、milestones、timeline_url、msclkid、prior_calls、total_calls、person_id です。リソースごとの全フィールド一覧については、CallRail API のドキュメントを参照してください。

ツールのアノテーション

すべてのツールで MCP ツールのアノテーションを宣言しています。33 個の読み取りツールには readOnlyHint、削除と一括書き込みには destructiveHint、更新には idempotentHint を指定しています。また、電話網に接続する create_outbound_call には openWorldHint を指定しています。アノテーションに対応したクライアントは、読み取りを自動承認し、書き込みの前に確認を求めることができます。

CallRail の公式 MCP サーバーとの比較

CallRail は OAuth 2.0 を使用するホステッド型の公式 MCP サーバーを提供しています（apidocs.callrail.com にドキュメントがあります）。ツールは約 30 個で、サーバー URL は CallRail のアカウントチームから提供されます。完全に管理されたリモートサーバーを利用したい場合に適しています。

この MCP サーバーは、別の用途のために作成しました。

	callrail-mcp（このプロジェクト）	公式 CallRail MCP
インストール	pip install callrail-mcp。2 分で実行可能	CallRail のアカウントチームから提供される URL
ホスティング	ローカルの stdio で動作するため、API キーがマシンの外部に出ることはありません	ホステッド型のリモートサーバー（OAuth）
ツール	57	約 30
代理店向けツール	usage_summary によるコストの帰属、compare_periods、spam_detector、bulk_update_calls、call_eligibility_check	提供なし
安全ガード	confirm_billing、confirm_dialing、dry_run のデフォルト設定、厳格な入力検証	ドキュメントなし
ソース	MIT、オープンで監査可能	非公開

どちらも同じ基盤の REST API v3 を使用します。複数のクライアントアカウントを扱う代理店で、コストの帰属や一括ワークフローが必要な場合に備えて、自分用に作成したのがこちらです。

コミュニティ製の TypeScript サーバーもあります。npm の @kanopi/callrail-mcp です（ツール 34 個、stdio、API キー認証）。このサーバーに追加したのは、代理店向けツール、安全ガード、CallRail のドキュメントと実際のレスポンスに照らして確認したリクエストコントラクトです（CHANGELOG の 1.3.0 の項目を参照してください）。

対象外（意図的に未実装）

以下の CallRail の機能は、設計上、この MCP では利用できません。対応するアカウントをお持ちの場合は PR を歓迎します。または、issue を作成してください。優先して対応します。

CallRail アカウントの権限でブロックされる機能（403 を返す）

以下のエンドポイントは存在しますが、私の標準的な CallRail アカウントにはないアカウントのアップグレードや権限が必要です。2026-10-05 に実際の環境で再確認しました。

• SMS/MMS の送信（POST /text-messages.json）には A2P/TCR SMS 登録が必要です。CallRail は、送信するテキストメッセージに TCPA 準拠のキーワード（STOP、CANCEL、UNSUBSCRIBE）を含めることを義務付けています。MMS サポートは 2026-05-05 に CallRail によって追加されました。
• Webhook インテグレーションの作成、更新、削除（type=Webhook を指定した POST /integrations.json）には Integration-Admin 権限が必要です。
• 発信者番号（/caller_ids.json の CRUD）は CallRail のドキュメントに記載されていますが、標準アカウントでは 403 が返されます。
• メッセージフロー（/message-flows.json の CRUD、SMS 自動返信フロー）はドキュメントに記載されていますが、403 が返されます。
• インテグレーションフィルター（/integration_triggers.json の CRUD）はドキュメントに記載されていますが、403 が返されます。
• アカウント内のどの会社でもフォームトラッキングが有効になっていない場合、フォーム送信エンドポイントは 403 を返します。 これは権限ではなくアカウントの状態によるものです。いずれかの会社でフォームトラッキングを有効にすると、エンドポイントを利用できます。ツールはエラー内でその旨を示します。

CallRail の REST API で公開されていない機能

これらは API に相当するものがなく、CallRail の Web UI からのみ管理できます。

• 番号：アカウントレベルでの番号の所有権、ポーティング、移管。
• コールフロー：IVR ビルダーとコールルーティングツリーの設定。
• カスタムフィールドの CRUD：カスタムデータ列は通話とフォームのレスポンスの一部として読み取れますが、スキーマ管理用のエンドポイントは公開されていません。
• Do Not Call リスト：DNC 番号の管理。

利用可能だが、まだリリースしていない機能

標準アカウントで読み取り可能ですが、現時点では価値が低いと判断しています。summary_emails の CRUD、companies/bulk_update.json（外部フォームのキャプチャのみ）、form_submissions/ignored_fields.json です。

使用例

> List companies under our CallRail account.

(calls list_companies, returns clients with IDs and primary numbers)

> Pull today's calls for company COM019ab..., include source and keyword.

(calls list_calls with company_id, days=1, fields="source,keywords,landing_page_url")

> Why is my CallRail bill $174 this month? Break it down by client.

(calls usage_summary, returns per-company cost share sorted by biggest user)

> Why didn't this call show up as a conversion in Google Ads? CAL019dbf79...

(calls call_eligibility_check, returns gclid, duration, and answered checks
 plus a targeted reason such as "duration 58s under Google Ads minimum (60s)")

> Show me everything this lead has done with us.

(calls list_leads then get_lead_timeline, returns calls, forms, and texts in one timeline)

> Provision a new Google-Ads-call-extension tracker for Alan Construction in 412.

(calls create_tracker, refuses unless you also pass confirm_billing=True
 since it incurs a monthly charge)

Python から直接使用する

CallRailClient はライブラリとしても使用できます。

from callrail_mcp.client import CallRailClient

cr = CallRailClient()  # picks up CALLRAIL_API_KEY
aid = cr.resolve_account_id()
for call in cr.paginate(f"a/{aid}/calls.json", {"per_page": 250}, items_key="calls"):
    print(call["id"], call.get("source"), call.get("customer_name"))

paginate() は省略可能な stats 辞書を受け取ります。この辞書には pages_fetched、items_yielded、total_records、truncated が記録されるため、上限によって切り詰められた結果と完全な結果を区別できます。

サーバーを直接実行する

デバッグする場合や、キーが機能することを確認する場合：

python -m callrail_mcp

サーバーは MCP stdio で通信します。stdin で JSON-RPC メッセージを待ち受けます。終了するには Ctrl-C を押してください。

MCP のループを実行せずに API キーを簡単にテストするには：

python -c "from callrail_mcp.client import CallRailClient; c=CallRailClient(); print(c.get('a.json'))"

レート制限

CallRail が公開しているデフォルトの制限は、一般的な API リクエストが 1 時間あたり 1,000 件、1 日あたり 10,000 件です。SMS 送信（1 時間あたり 150 件、1 日あたり 1,000 件）と発信通話（1 時間あたり 100 件、1 日あたり 2,000 件）には、それぞれ別の上限が設定されています。クライアントは Retry-After ヘッダーを使って 429 レスポンスを再試行し、冪等なメソッド（GET、PUT、DELETE、HEAD、OPTIONS）に限り、指数バックオフで 5xx レスポンスを再試行します。POST は 5xx の場合でも再試行されないため、レスポンスが失われてもトラッカーが重複して作成されることはありません。大量のページネーションでは、組み込みの paginate() ヘルパーを使用してください。

開発

git clone https://github.com/pghdma/callrail-mcp
cd callrail-mcp
python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"
pytest

リリースの流れ、知っておくべき API の仕様、そしてこのコードベースで採用している規約については、DEVELOPMENT.md をご覧ください。

コントリビューション

コントリビューションを歓迎します。開発環境のセットアップ、テストの規約、リリースの流れについては、CONTRIBUTING.md をご覧ください。問題は GitHub Issues から報告し、行動規範に従ってください。

セキュリティ

セキュリティの脆弱性を発見した場合は、公開の問題として報告するのではなく、SECURITY.md に従って非公開でお知らせください。

作者

Steve Japalucci、Pittsburgh Digital Marketing Agency の創業者です。自身のクライアントアカウントで毎日使用しているため、バグはすぐに見つかり、修正されます。[email protected] までご連絡ください。

ライセンス

MIT。LICENSE をご覧ください。Copyright (c) 2026 Steve Japalucci / Pittsburgh Digital Marketing Agency.

免責事項

このプロジェクトは独立したオープンソースの統合であり、CallRail とは提携関係になく、CallRail から推奨または公式にサポートされているものでもありません。「CallRail」は CallRail, Inc. の商標です。すべての製品名、ロゴ、ブランドは、それぞれの所有者に帰属します。