SMS.ir MCP サーバー

SMS.ir Panel V2 API のための厳選された、安全ゲート付きツールセットを公開するローカル Model Context Protocol サーバーです。Python + FastMCP で構築されています。

• Codex / Claude Desktop / Claude Code 用の stdio トランスポート

• ローカル開発・テスト用の streamable HTTP トランスポート

• 読み取り操作はそのまま動作します。すべての送信は課金対象であり、デフォルトでブロックされ、確認フラグ と サーバー側のキルスイッチの両方が必要です。

• 電話番号、メッセージ本文、API キー、OTP コードはログでマスクされます。

SMS.ir Panel V2 Postman コレクション（このリポジトリには含まれていません — 実際の API キーが埋め込まれているため）から構築されています。正規化された API の説明は docs/API.md と docs/openapi.yaml にあります。

1. セットアップ

Python 3.10+ が必要です（CPython 3.12 で開発・テスト済み）。

cd C:\Users\Kasra\Documents\sms.ir-mcp

# create the project-local virtual environment
py -3.12 -m venv .venv

# install runtime deps (pinned)
.\.venv\Scripts\python.exe -m pip install -r requirements.txt

# ...or install with the package + dev/test extras
.\.venv\Scripts\python.exe -m pip install -e ".[dev]"

Related MCP server: iletiMerkezi MCP Server

2. 設定

すべての設定は環境変数から取得されます。ローカルで使用する場合は、サンプルの env ファイルをコピーして記入してください — これは git で無視され、コミットされることはありません。

copy .env.example .env
notepad .env

実際の環境変数は、env ファイルの値よりも常に優先されます。

3. 実行

# stdio (what MCP clients launch)
.\.venv\Scripts\python.exe -m sms_ir_mcp --transport stdio

# streamable HTTP for local testing (http://127.0.0.1:8000/mcp)
.\.venv\Scripts\python.exe -m sms_ir_mcp --transport http --host 127.0.0.1 --port 8000

クレジットを消費しない簡単な接続・認証チェックには、接続済みの任意のクライアントから health_check ツール（または get_balance）を呼び出してください — どちらも内部的には GET /v1/credit です。

4. ツール

読み取り専用ツールは常に利用可能です。書き込みツールには confirm=true と SMSIR_ALLOW_SEND=true の両方が必要です。破壊的ツールには confirm=true が必要です。

すべてのツールは、成功時には {"ok": true, "data": …, …} を、失敗時には {"ok": false, "error": {"code": …, "message": …}} を返します。エラーコード: config_error、validation_error、confirmation_required、send_disabled、auth_error、rate_limited、transient_error、api_error、internal_error。

例

// check balance
get_balance() -> {"ok": true, "data": {"credit": 45210}}

// read the latest OTP received on a given number
extract_latest_otp({"mobile": "9821000"})
  -> {"ok": true, "data": {"otp": "834122", "matched": true, "from": "*****1000", ...}}

// attempt a send without confirming -> refused, nothing sent
send_sms({"message_text": "Hi", "mobiles": ["09121234567"]})
  -> {"ok": false, "error": {"code": "confirmation_required", ...}}

// confirmed send, but kill switch still off -> refused, nothing sent
send_sms({"message_text": "Hi", "mobiles": ["09121234567"], "confirm": true})
  -> {"ok": false, "error": {"code": "send_disabled", ...}}

// edited .env to set SMSIR_ALLOW_SEND=true -> apply it without restarting
reload_config()
  -> {"ok": true, "data": {"config": {"allow_send": true, ...}, "changed": ["allow_send"]}}

// with SMSIR_ALLOW_SEND=true AND confirm=true -> actually sends (billable)
send_sms({"message_text": "Hi", "mobiles": ["09121234567"],
          "line_number": "30007732000000", "confirm": true})
  -> {"ok": true, "data": {"packId": "…", "messageIds": [123], "cost": 1.0}, "recipients": 1}

5. 安全モデル

• 課金対象の操作（send_sms、send_verification_code、send_personalized_sms）には両方が必要です:

  1. ツール呼び出しでの confirm=true、および

  2. サーバー環境での SMSIR_ALLOW_SEND=true。 キルスイッチがオフの場合、確認済みの呼び出しでも何も送信されません。

• 破壊的操作（cancel_scheduled_send）には confirm=true が必要です。

• 任意のベース URL は不可: SMSIR_ALLOW_CUSTOM_BASE_URL=true でない限り、api.sms.ir のみ受け入れられます。HTTPS が強制されます。

• ヘッダーインジェクションなし: 呼び出し元はリクエストヘッダーを設定できません。型指定され検証されたフィールドのみが転送されます。

• タイムアウト + 制限付き再試行 + クライアント側レート制限がすべてのリクエストに適用されます。

• マスキング: API キー、電話番号、メッセージ本文、OTP 値はログ出力でマスクされます。

• 管理エンドポイントなし: Postman コレクション内の操作のみが公開されます。アカウント / 設定管理用のものはありません。

6. クライアント登録

実際の API キーはこのフォルダの .env に置いてください — クライアント設定ファイルには決して入れないでください。以下の各設定は、クライアントをこのサーバーとその .env にポイントするだけです。

Codex CLI（インストール済み）

codex mcp add sms-ir `
  --env SMSIR_ENV_FILE=C:\Users\Kasra\Documents\sms.ir-mcp\.env `
  -- C:\Users\Kasra\Documents\sms.ir-mcp\.venv\Scripts\python.exe -m sms_ir_mcp --transport stdio

codex mcp list          # sms-ir should appear
codex mcp get sms-ir

手動での同等設定: docs/codex_config.example.toml

Claude Code（インストール済み）

このリポジトリにはプロジェクトスコープの .mcp.json が同梱されています。このディレクトリで Claude Code を開き、プロンプトが表示されたら sms-ir サーバーを承認してください:

cd C:\Users\Kasra\Documents\sms.ir-mcp
claude
/mcp                    # shows sms-ir and its tools

代わりにユーザースコープで登録する場合:

claude mcp add sms-ir --scope user `
  --env SMSIR_ENV_FILE=C:\Users\Kasra\Documents\sms.ir-mcp\.env `
  -- C:\Users\Kasra\Documents\sms.ir-mcp\.venv\Scripts\python.exe -m sms_ir_mcp --transport stdio

Claude Desktop（未インストール）

インストールしたら、docs/claude_desktop_config.example.json を %APPDATA%\Claude\claude_desktop_config.json にマージしてください（事前にバックアップを取り、他のサーバーは保持してください）。

7. 開発

.\.venv\Scripts\python.exe -m ruff check src tests
.\.venv\Scripts\python.exe -m ruff format --check src tests
.\.venv\Scripts\python.exe -m pytest

テストでは、リクエスト構築、認証ヘッダー、エンベロープ解析、エラー正規化、再試行 / レート制限、引数検証、マスキング、OTP 抽出、すべてのツールのモック統合（Postman のサンプルペイロードを使用）、OpenAPI とコレクションの整合性、MCP ツールの検出をカバーしています。

8. 最初のライブテスト（資格情報を提供した後）

このリポジトリ内の何も、課金対象の呼び出しを行ったことはありません。最初の実際の送信を実行するには、明示的に承認する必要があります:

1. キーを .env に置きます:

   SMSIR_API_KEY=<your real key>
   SMSIR_DEFAULT_LINE_NUMBER=<your approved line>
   SMSIR_ALLOW_SEND=true

2. 費用をかけずに接続を確認します — 接続済みのクライアントから health_check（または get_balance）を呼び出します。

3. そのときだけ、最初の課金対象の呼び出しを行います。正確なツール呼び出し:

   send_sms({
     "message_text": "SMS.ir MCP test",
     "mobiles": ["<your own mobile>"],
     "line_number": "<your approved line>",
     "confirm": true
   })

   Codex での表現: "Use the sms-ir server's send_sms tool to send 'SMS.ir MCP test' to from line , with confirm true."

9. トラブルシューティング