joltsms-sms

@joltsms/mcp-server

JoltSMS 用の MCP サーバーです。専用の実SIM対応米国電話番号を取得し、AI エージェントを通じて SMS／OTP コードを受信できます。

Model Context Protocol に基づいて構築されたこのサーバーを使うと、AI エージェント（Claude Code、Claude Desktop、Cursor など）が、標準化されたツール呼び出しを通じて電話番号のレンタル、受信 SMS の待機、OTP コードの抽出、請求情報の管理を行えるようになります。

クイックスタート

1. API キーを取得する

JoltSMS アカウントを作成し、ダッシュボード → 設定 → API キー で API キーを生成します。

2. MCP クライアントを設定する

.mcp.json（Claude Code）または MCP 設定（Claude Desktop、Cursor）に追加します。

{
  "mcpServers": {
    "joltsms": {
      "command": "npx",
      "args": ["-y", "@joltsms/mcp-server@2"],
      "env": {
        "JOLTSMS_API_KEY": "jolt_sk_your_key_here"
      }
    }
  }
}

3. 使用する

これで、AI エージェントから JoltSMS の 12 個すべてのツールを利用できるようになります。次のように試してみてください。

「保存済みのカードを一覧表示してから、選んだカードを使って次に利用可能な番号をレンタルして。」

ツール

ツール	説明
joltsms_list_numbers	サービスラベル、タグ、未読数を含む有効な番号の一覧を表示します
joltsms_get_number	1 つの番号の詳細を取得します
joltsms_update_number	番号にサービスラベル、タグ、メモを設定します
joltsms_list_payment_methods	マスキングされた保存済みカードと支払い方法 ID を一覧表示します
joltsms_provision_number	次に利用可能な番号をレンタルします。必要に応じて選択した保存済みカードを使用できます（$50/月）
joltsms_release_number	期間終了時に自動更新を停止するか、未払いの初回チェックアウトをキャンセルします
joltsms_list_messages	OTP コードとメッセージ ID を解析した最近の SMS を一覧表示します
joltsms_reply_to_sms	対象となる受信メッセージに返信します（最大 15 文字）
joltsms_mark_read	メッセージを個別または一括で既読にします
joltsms_wait_for_sms	SMS が届くまでポーリングします（OTP フローの主要ツール）
joltsms_get_latest_otp	直近の解析済み認証コードを取得します
joltsms_billing_status	最大 10 件のサブスクリプションについて請求状況を確認します

ツールのアノテーション（2.0.2）

12 個すべてのツールは、人が読める annotations.title と明示的なブール値の readOnlyHint、destructiveHint、idempotentHint、openWorldHint を tools/list を通じて公開します。

ツール	読み取り専用	破壊的	冪等	オープンワールド
番号の一覧表示、番号の取得、支払い方法の一覧表示、メッセージの一覧表示、SMS の待機、最新 OTP の取得、請求状況	true	false	true	false
番号のメタデータ更新	false	true	true	false
番号の取得、番号の解約、SMS への返信	false	true	false	true
メッセージを既読にする	false	false	true	false

「破壊的」には、ラベル／タグ／メモの上書き、金銭の支払い、サービスの解約、取り消せない SMS の送信が含まれます。アカウント情報の読み取りと既読状態の更新は、プライベートな JoltSMS アカウント内で完結します。レンタル、解約、返信は、アカウント外の決済サービスや通信サービスとやり取りします。

番号の取得では保留中の試行が保護されますが、成功後に新しい呼び出しを行うと、別の番号を購入する可能性があります。返信では、呼び出しごとに新しいリクエストキーを使用します。解約では呼び出しごとに新しい API リクエストを送信し、安全な自動再試行は保証されません。これらのヒントは、クライアントが操作を正確に提示するのに役立ちます。認可された操作には、引き続き API 権限とユーザーの承認が必要です。

バージョン 2.0.2 では、同梱の ip-address も 10.7.4 に更新され、GHSA-rxp7-6hxx-x8q5 に対応しています。

OTP 認証ワークフロー

最も一般的なユースケースである、電話番号認証の自動化です。

1. joltsms_provision_number({ payment_method_id: "pm_chosen_from_saved_cards" })
   → Number provisioning started! Use joltsms_list_numbers to check when it is ACTIVE.

2. joltsms_list_numbers({})
   → Once provisioning completes: +17245550100 (ACTIVE)

3. joltsms_update_number({ number_id: "+17245550100", service_name: "PayPal" })
   → Tagged for easy lookup later

4. [Agent enters phone number on PayPal and requests OTP]

5. joltsms_wait_for_sms({ number_id: "+17245550100", timeout_seconds: 120 })
   → SMS received after 8.2s: "Your PayPal code is 847291"
   → OTP Code: 847291

6. joltsms_mark_read({ number_id: "+17245550100" })
   → Inbox clean

7. [Agent enters 847291 on PayPal — verification complete]

環境変数

変数	必須	説明
JOLTSMS_API_KEY	はい	API キー（jolt_sk_*）
JOLTSMS_API_URL	いいえ	API のベース URL（デフォルトは https://api.joltsms.com）

要件

• パッチ適用済みの Node.js リリース：22.x の 22.23.4 以降、24.x の 24.22.1 以降、または 26.x の 26.12.1 以降
• 支払い方法が登録済みの JoltSMS アカウント
• 支払い認証が必要な場合は、ツールから返されたホスト型請求書 URL を開いてください
• SMS への返信には、SMS 返信機能を備えた API キーが必要です

Node.js セキュリティアップデート（2.0.1）

バージョン 2.0.1 では、2026 年 10 月 21 日の Node.js セキュリティパッチが必要です。 起動時に Node のランタイムを確認し、古いパッチ、サポート対象外のメジャーバージョン、またはプレリリース版が使われている場合は、アップグレードを促すメッセージを表示して終了します。npm のエンジン警告だけでは、この要件は適用されません。

npx でインストールする場合は、MCP クライアントを起動するマシンで Node を更新し、その環境で node --version を確認してから、MCP 接続を再起動してください。クライアントはターミナルとは異なる PATH を使う場合があります。クライアントの環境でもパッチ適用済みの Node バイナリが選択されていることを確認してください。新しい npm パッケージをインストールしても、Node 自体は置き換わりません。Docker ビルドでは両方のステージで node:22.23.4-slim を使用します。パッチ適用済みのランタイムを使うには、既存のコンテナを再ビルドして置き換えてください。

API キー、実行可能ファイル名、12 個すべてのツールに変更はありません。

1.x からのアップグレード

上記のパッチ適用済み Node.js バージョンのいずれかを使用し、固定された MCP 設定を @joltsms/mcp-server@2 に変更してから、MCP 接続を再起動してください。既存の JoltSMS API キーと、mcp-server／joltsms-mcp という実行可能ファイル名は引き続き使用できます。

市外局番は選択できません。古い area_code 引数を削除してください。レンタルでは、次に利用可能な米国専用携帯電話番号が使われます。プロビジョニングを呼び出すたびに 1 つの番号が注文されます。複数番号をまとめたチェックアウトは、引き続きダッシュボードで利用できます。

保存済みのカードを選択するには、joltsms_list_payment_methods を呼び出し、ユーザーにカードを選択してもらって、その payment_method_id を joltsms_provision_number に渡してください。省略した場合は、有効なアカウントのデフォルトカード、または保存済みのカードが 1 枚のみの場合はそのカードが使用されます。認証が必要な場合、ツールはホスト型請求書 URL と保留中のサブスクリプション ID を返します。支払いが完了していないチェックアウトは、放置された場合でも joltsms_release_number でキャンセルできます。支払い済みのレンタルは、顧客の請求期間が終了するまでサービスが維持されます。

番号の詳細には、顧客へのサービス提供終了日と次回請求日／再試行日が別々に表示されます。プロバイダー側のレンタル期限は、顧客へのサービス終了日ではありません。番号一覧と請求概要には最大 10 件まで表示されます。アカウントにそれより多くの番号がある場合は、joltsms_get_number で特定の番号を検索するか、全件表示にはダッシュボードを使用してください。

返信の送信先は、既存の受信メッセージ ID です。任意の宛先を指定したり、アウトバウンドキャンペーンを有効にしたりすることはできません。

開発

npm ci --ignore-scripts
npm test
npm run test:package
npm audit --audit-level=low

ソースの同期、互換性チェック、npm と MCP Registry それぞれの公開手順については、RELEASING.md を参照してください。

ドキュメント

• MCP サーバーのドキュメント
• API リファレンス
• JoltSMS のウェブサイト

ライセンス

MIT