MobileValidate

@mobilevalidate/mcp

Model Context Protocol に対応した MobileValidate のサーバーです。 AI エージェント（Claude Desktop、Claude Code、Cursor、VS Code など、あらゆる MCP クライアント）から、電話番号の各プラットフォーム（WhatsApp、Telegram、Viber、Signal など）への登録状況、通信事業者と回線の種類、報告ベースのスパム評価、およびメールアドレス（メールボックスの存在、Gmail、Outlook、Apple などのアカウントの有無。名前やプロフィールは一切取得せず、はい／いいえ／不明のみ）を確認できます。1 回の呼び出しで複数のサービスを確認でき（checks）、list_services で API キーが利用できるサービスを確認できます。

公開されている MobileValidate API の薄いクライアントで、mobilevalidate SDK を基盤に構築されています。このサーバー自体は認証情報を保持しません。お使いのキーは api.mobilevalidate.com に転送されるだけです。

利用方法は 2 通りです。

	ホスト型（リモート）	ローカル（stdio）
実行場所	https://mcp.mobilevalidate.com/mcp（Streamable HTTP）	お使いのマシン上で npx -y @mobilevalidate/mcp を実行
キー	ヘッダー Authorization: Bearer <key>	環境変数 MOBILEVALIDATE_API_KEY
必要なもの	インストール不要	Node.js ≥ 20（npx がパッケージをダウンロードします）

どちらも、同じ利用料保護機能を備えた同じツールを実行します。テストキーを使ってどちらかをお試しください。ドキュメントに記載されているテスト値は固定の結果を返し、課金されることはありません。

キーには エージェントキー（mv_agent_…、スコープ制限あり、日次利用上限あり）と テストキー（mv_test_…、無料、課金なし）があります。ライブキー（mv_live_…）は意図的に MCP サーバーで拒否されます。個人用テストキーは https://mobilevalidate.com/get-test-key で取得できます。エージェントキーは、承認済みのアカウントで利用できます。

ドキュメント：https://mobilevalidate.com/docs/mcp

クイックスタート（ホスト型、テストキー）

export MOBILEVALIDATE_API_KEY=mv_test_...     # your personal test key
claude mcp add --transport http mobilevalidate https://mcp.mobilevalidate.com/mcp \
  --header "Authorization: Bearer $MOBILEVALIDATE_API_KEY"

次に、「+447700900001、+447700900002、+447700900003 の WhatsApp 登録状況を確認してください。」 と尋ねてください。「登録済み」「未登録」「不明」の結果が返されます。テストキーでは実際のネットワークに接続されず、課金もされません。以下のマジック値には固定の結果が返され、それ以外の電話番号には、作成された一貫性のある結果が返されます。

試してみたいだけですか？ 公開サンドボックスキー mv_test_publicSandboxn9ZgneuhR1B9CRfKG3fulym も利用できますが、以下のマジック値のみに回答し（それ以外は sandbox_magic_only で拒否されます）、共有のレート制限が低く、大規模なジョブは実行できません。それ以外の用途には、ご自身のテストキーをお使いください。

テスト用電話番号	結果
+447700900001	登録済み
+447700900002	未登録
+447700900003	不明（registered: null）
+447700900004	約 5 秒間保留の後、登録済み
+447700900005	unsupported_country
+447700900006	登録済み、ビジネスアカウント

テスト用メールアドレス：[email protected]、not-registered@…、unknown@…（同じドメイン）。全リスト： https://mobilevalidate.com/docs/test-values。

クライアントの設定

Claude Code

# hosted
claude mcp add --transport http mobilevalidate https://mcp.mobilevalidate.com/mcp \
  --header "Authorization: Bearer $MOBILEVALIDATE_API_KEY"
# local stdio
claude mcp add mobilevalidate --env MOBILEVALIDATE_API_KEY=mv_agent_... -- npx -y @mobilevalidate/mcp

ホスト型の設定に相当する .mcp.json の設定：

{
  "mcpServers": {
    "mobilevalidate": {
      "type": "http",
      "url": "https://mcp.mobilevalidate.com/mcp",
      "headers": { "Authorization": "Bearer ${MOBILEVALIDATE_API_KEY}" }
    }
  }
}

Cursor（~/.cursor/mcp.json または .cursor/mcp.json）

ホスト型（ライブ）：

{
  "mcpServers": {
    "mobilevalidate": {
      "url": "https://mcp.mobilevalidate.com/mcp",
      "headers": { "Authorization": "Bearer ${env:MOBILEVALIDATE_API_KEY}" }
    }
  }
}

ローカル stdio：{ "mcpServers": { "mobilevalidate": { "command": "npx", "args": ["-y", "@mobilevalidate/mcp"], "env": { "MOBILEVALIDATE_API_KEY": "mv_agent_..." } } } }

VS Code（.vscode/mcp.json）

{
  "servers": {
    "mobilevalidate": {
      "type": "http",
      "url": "https://mcp.mobilevalidate.com/mcp",
      "headers": { "Authorization": "Bearer ${input:mobilevalidate-key}" }
    }
  },
  "inputs": [
    { "id": "mobilevalidate-key", "type": "promptString", "description": "MobileValidate agent or test key", "password": true }
  ]
}

Claude Desktop（claude_desktop_config.json）

Claude Desktop は、ホスト型サーバーのライブキーを、コミュニティ製の mcp-remote パッケージなどの stdio ブリッジ経由でリモートサーバーに接続します。

{
  "mcpServers": {
    "mobilevalidate": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://mcp.mobilevalidate.com/mcp", "--header", "Authorization:Bearer ${MOBILEVALIDATE_API_KEY}"],
      "env": { "MOBILEVALIDATE_API_KEY": "mv_agent_..." }
    }
  }
}

ローカル stdio：

{
  "mcpServers": {
    "mobilevalidate": {
      "command": "npx",
      "args": ["-y", "@mobilevalidate/mcp"],
      "env": { "MOBILEVALIDATE_API_KEY": "mv_agent_..." }
    }
  }
}

その他の MCP クライアント

• Streamable HTTP： URL https://mcp.mobilevalidate.com/mcp、ヘッダー Authorization: Bearer mv_agent_…。サーバーはステートレスです。POST のみを受け付け、JSON レスポンスを返し、セッション ID は使用しません。
• stdio： コマンド npx、引数 ["-y", "@mobilevalidate/mcp"]、環境変数 MOBILEVALIDATE_API_KEY=mv_agent_…。バージョンを固定するには @mobilevalidate/[email protected] を指定してください。npm install -g @mobilevalidate/mcp の実行後は、コマンド mobilevalidate-mcp を使用します。

プロトコルのバージョン

どちらのトランスポートも、MCP 2026-07-28 と、ハンドシェイク方式の以下のリビジョンに対応しています：2025-11-25、2025-06-18、2025-03-26、 2024-11-05、2024-10-07（1.1.0 以降。1.0.x の対応は 2025-11-25 まで）。設定は不要です。クライアントが最初に送信するメッセージによって、リビジョンが選択されます。

• 2026-07-28： initialize はありません。各リクエストには _meta（io.modelcontextprotocol/protocolVersion、クライアント情報、ケイパビリティ）が含まれます。また、HTTP では MCP-Protocol-Version、Mcp-Method、Mcp-Name ヘッダーも含まれます（本文との整合性が検証され、不一致の場合は 400、-32020）。server/discover は、サポートされているバージョン、ケイパビリティ、サーバーの識別情報、説明を返します。tools/list と server/discover には ttlMs: 3600000, cacheScope: "public" が含まれます（リストはキーに関係なく同じです）。ツールは固定の順序で返されます。サポートされていないバージョンの場合は、サポート対象のバージョンを示す UnsupportedProtocolVersion（-32022）とともに 400 が返されます。ツール呼び出しは JSON を返します（SSE なし）。
• 2025 年代のクライアント： 従来どおり initialize を使用します。ホスト型サーバーはステートレスのままです（POST のみ、JSON レスポンス、セッション ID なし。GET → 405）。stdio では、接続はネゴシエートされたリビジョンで維持されます。
• サーバーはサーバーからクライアントへのリクエスト（サンプリング、エリシテーション、ルート）も、プロトコルログも使用しないため、2026-07-28 で非推奨になった機能は関係ありません。一括ジョブでは明示的な job_id ハンドルを使用します。これは、セッションが廃止された現在、仕様が推奨するパターンです。
• サーバーカードの supportedProtocolVersions には、同じバージョンが新しい順に列挙されています。

ツール

ツール	説明	クレジットを消費	アノテーション
normalize_numbers	ローカルで無料の E.164 形式への変換です。曖昧な入力（国の指定なし）と重複を検出します	いいえ	読み取り専用、冪等、閉世界
estimate_cost	無料の事前確認（電話番号および／または emails）：有効、無効、重複、キャッシュ済みの件数と、一括ジョブの最大コストを返します	いいえ	読み取り専用、冪等
lookup_numbers	最大 100 件の電話番号（任意で emails を含め、合計 100 件まで）について、1 つ以上のリアルタイムサービスを確認します（checks。最大 wait_seconds 秒待機。デフォルトは 20）	はい	読み取り専用ではない、冪等、開世界
lookup_emails	最大 100 件のメールアドレスをリアルタイムで確認します（デフォルトのチェックは email。例：apple.email）	はい	読み取り専用ではない、冪等、開世界
check_spam_reputation	最大 100 件の電話番号のスパム評価を確認します（number.spam のみを実行）：番号ごとの risk_level、risk_score、理由、主なカテゴリ、初回／最終確認日時、情報源と、レベルごとの件数を返します	はい	読み取り専用ではない、冪等、開世界
create_lookup_job	有効なサービス（gmail などの一括処理専用サービスを含む）を対象に、最大 50,000 件の電話番号および／または emails を一括確認します。job_id を返します	はい	読み取り専用ではない、非冪等（同じ引数による再試行は重複排除されます）
get_lookup_job	ジョブのステータスと、フィルター（registered、service）を適用した、ページネーション付きの結果ページを返します（電話番号またはメールアドレスごとに 1 項目）	いいえ	読み取り専用、冪等
list_services	キーで利用可能なサービス：入力タイプ（電話／メール）、リアルタイムか一括処理専用か、属性、国、料金	いいえ	読み取り専用、冪等
get_account	残高、予約済みクレジット、本日の利用状況、上限	いいえ	読み取り専用、冪等

すべてのツールは title、アノテーション、inputSchema、outputSchema を宣言します。それぞれが structuredContent と、1 行のテキスト要約を返します。checks にはサービスコードまたはエイリアス（例：whatsapp、telegram、viber、carrier、spam）を指定します。説明には、このビルドで認識されるリアルタイムおよび一括処理専用のコード（SDK の生成カタログに基づく）が記載され、list_services は最新のリストを返します。結果項目には v1 の最上位フィールド（WhatsApp がリクエストされた場合は WhatsApp、そうでない場合は最初のサービス）が維持され、複数のサービス（または WhatsApp 以外のサービス）がリクエストされた場合は、サービスごとの checks マップが追加されます。ツールの説明には、列挙を防止するための上限（連続する番号が 20 件以上の場合は拒否、1 日あたりの上限）が記載されています。 メール。 電話サービスでは numbers、メールサービスでは emails を使用します。送信する種類ごとに、少なくとも 1 件の確認を送信してください。結果の項目には kind（phone／email）が含まれます。メール項目には email（正規化済み。無効な場合は null）、email_status（valid、invalid_email、duplicate、suppressed）が含まれ、number_status: null となります。説明にはメールのルールが記載されています。同じドメインで数字だけが異なるアドレスが 20 件以上ある場合、列挙として拒否されます。また、回答は yes／no／unknown のみで、名前、写真、プロフィールは含まれません。テストキーでは [email protected]、not-registered@…、unknown@… を使用します（同じドメイン）。

スパム評価。 check_spam_reputation（または他のツールで checks: ["spam"] を指定）は、スパムや迷惑電話の報告に基づいて回答します。対象には、規制当局の措置、政府の苦情データ、コミュニティからの報告、最近割り当て解除された番号が含まれます。制裁対象国（キューバ、イラン、北朝鮮、シリア、ロシア、ベラルーシ、ベネズエラ、および制裁対象地域）を除くすべての国が対象です。制裁対象の場合は unsupported_country となり、無料です。no_reports は報告が知られていないことを意味し、番号が安全であることを意味するものではありません。それでも確定回答として課金されます。上限は 1 回の呼び出しにつき番号 100 件です。支出確認と列挙防止のルールは lookup_numbers と同じです。テストキーでは、+447700900001 は high、…002 は no_reports、…003 は unknown、…004 は pending の後 medium、…005 は unsupported_country となります。属性値は整数（risk_score、sources）の場合があります。

ネットワーク確認。 checks: ["hlr"] はリアルタイムのネットワーク状態（status は reachable／unreachable／invalid、ported、roaming、mcc_mnc、country）を返します。checks: ["mnp"] は番号ポータビリティ（porting は ported／not_ported、mcc_mnc、country）を返します。不明な回答は無料です。

支出の安全対策

lookup_numbers、lookup_emails、check_spam_reputation、create_lookup_job が支出を伴う処理を行う前に、サーバーは無料の見積もりを呼び出します。リアルタイムツールはキーのリアルタイム料金（list_services から取得）での上限額を、create_lookup_job は一括料金での上限額を提示します。次のいずれかに該当する場合、呼び出しは confirmation_required エラー結果とともに拒否されます。

• 上限額が MCP_CONFIRM_ABOVE_USD（既定値は 1.00）を超える場合、または
• ジョブに含まれる番号とメールアドレスの合計が 100 件を超える場合。

スコープ（エージェントキー）：リアルタイムツールには lookup:write と jobs:write が必要です（見積もりは POST /v1/jobs/estimate）。estimate_cost と create_lookup_job には jobs:write、get_lookup_job には jobs:read、 get_account には account:read が必要です。list_services にスコープは必要ありません。

エラーテキストには金額が記載され、エージェントにユーザーへの確認を求めます。その後、エージェントは表示された金額を confirm_max_cost に設定してツールを再度呼び出します。確認済み（または見積もり済み）の金額は常に max_cost として API に送信されるため、これを超える費用が発生するリクエストは API に拒否されます。

制限事項： この確認はエージェントを介して行われます。サーバーは、人間が金額を承認したことを証明できません。上限を設けるのはキー自体の支出上限と max_cost ガードです。人間による確認用 URL は今後提供予定です。

その他のルール：

• mv_agent_…（スコープ設定済み、支出上限あり）および mv_test_… キーのみ使用できます。mv_live_… キーは明確なメッセージとともに拒否されます。
• webhook_url パラメーターはなく、リクエストのメタデータがツール出力に返されることもありません。
• ログは stderr に出力され、件数と ID のみが含まれます。電話番号やメールアドレスとみられるものはすべてマスキングされます。

環境変数

環境変数	デフォルト	使用先
MOBILEVALIDATE_API_KEY	なし（必須）	stdio：mv_agent_／mv_test_ キー
MOBILEVALIDATE_BASE_URL	https://api.mobilevalidate.com	両方
MCP_CONFIRM_ABOVE_USD	1.00	両方
MCP_HOST / MCP_PORT	127.0.0.1 / 3300	HTTP
MCP_ALLOWED_HOSTS	なし	HTTP：許可する追加の Host 値（カンマ区切り）。リバースプロキシの背後に配置する場合など
MCP_LOG	オン	stderr のログを無効にするには off を設定
MV_MCP_FORWARD_SECRET	なし	HTTP、ホスト型デプロイのみ：API と共有するシークレット。サンドボックスキーの呼び出しをサーバー単位ではなく、エンドクライアント単位でレート制限します
MCP_CLIENT_IP_HEADER	cf-connecting-ip	HTTP：エンドクライアントの IP を含むヘッダー。ループバックピア（トンネル／プロキシ）からの接続の場合のみ信頼されます

HTTP トランスポートのセルフホスト

MCP_HOST=127.0.0.1 MCP_PORT=3300 npx -y -p @mobilevalidate/mcp mobilevalidate-mcp-http   # once published

POST /mcp のみ（ステートレス、JSON レスポンス。2026-07-28 と 2025 年世代のクライアントを同じエンドポイントで処理）と GET /healthz。各リクエストの Authorization: Bearer キーは、そのリクエストに限って API に転送され、保存されることはありません。Host は 127.0.0.1:<port> または localhost:<port>、および MCP_ALLOWED_HOSTS に指定された値である必要があります（DNS リバインディング対策）。サーバーをリバースプロキシの背後に配置する場合はこの値を設定し、TLS をその手前で終端してください。リクエストボディの上限は 2 MB です。

セキュリティに関する注意事項

• 使用額の上限を許容範囲に設定したエージェントキー（mv_agent_…）を使用してください。キーの上限と max_cost ガードが厳格な上限となります。テストキーは無料です。
• キーはプロンプトではなく、クライアントの env／ヘッダー設定に格納してください。サーバーはキーをログに記録しません。stderr ログに含まれるのは件数と ID のみで、電話番号やメールアドレスに見えるものはすべてマスキングされます。
• MCP_CONFIRM_ABOVE_USD を超える支出には、エージェントが事前にユーザーへ確認する必要があります（支出の安全性を参照）。これはエージェントを介した確認のため、実際の上限としてキーの使用額上限を設定してください。
• ユーザーが正当な関係を持つ番号と住所のみを確認してください。列挙につながるパターンは拒否され、日次上限が適用されます。

メンテナー向け

ソースは src/ 内の TypeScript です（モノレポ内で tsx を使って直接実行します。HTTP は 127.0.0.1:3300 で pnpm --filter @mobilevalidate/mcp start、stdio は start:stdio を実行してください）。公開パッケージに含まれるのはコンパイル済みの dist/、README.md、LICENSE、server.json のみです。publishConfig は main／exports／bin を src/ から dist/ に切り替え、pnpm は workspace:* SDK 依存関係を正確な SDK バージョンに書き換えます。そのため、必ず pnpm（ops/publish-packages.sh）でパッケージを作成してください。このディレクトリから npm pack／npm publish を直接実行してはいけません。ビルドは SDK の dist/ 型定義を使ってコンパイルするため、先に SDK をビルドしてください。

MCP SDK：サーバーは公式 v2 TypeScript SDK（@modelcontextprotocol/server）を使用します。これは 2026-07-28 を実装し、HTTP では createMcpHandler と isLegacyRequest、stdio では serveStdio によって両世代のクライアントを処理します。v1 パッケージの @modelcontextprotocol/sdk と @modelcontextprotocol/client は開発依存関係のみです。テストではこれらを実際の 2025-11-25 クライアントと 2026-07-28 クライアントとして使用します（test/protocol.test.ts）。

pnpm --filter @mobilevalidate/mcp run typecheck
pnpm --filter @mobilevalidate/mcp test
pnpm --filter mobilevalidate run build && pnpm --filter @mobilevalidate/mcp run build   # → dist/
ops/publish-packages.sh                     # build, test, pack, leak-scan, npm publish --dry-run (SDK, then MCP)
NPM_TOKEN=… ops/publish-packages.sh --yes   # real publish

リリースチェックリスト：package.json の version、src/tools.ts の SERVER_VERSION、および server.json の両方の version フィールドを更新してください（一致していることをテストで検証します）。このパッケージは SDK の正確なバージョンを固定しているため、先に SDK を公開する必要があります。

MCP Registry。 com.mobilevalidate/mcp（ドメイン検証済み名前空間）として登録されています。server.json は Registry スキーマ 2025-12-11 に準拠しています。package.json の mcpName は name と一致する必要があります（Registry は npm 上でこれを確認します）。

ライセンス

MIT © 2026 BroadNet Technologies Inc. 詳細は LICENSE を参照してください。