mailsocket

mailsocket — MCP サーバー

mailsocket をネイティブツールとして AI コーディングエージェントに公開する MCP サーバーです。これにより、エージェントは一時的な受信トレイを作成し、ポーリングコードを書くことなく OTP またはマジックリンクを待機できます。Python SDK をラップしているため、2つ目の HTTP クライアントや、再実装されたポーリング処理は必要ありません。

機能

ツール	エージェントが取得できるもの
create_inbox(label?)	新しい受信トレイの id と address
wait_for_otp(inbox_id, timeout?=60, min_confidence?=0, since?)	主な機能 — 待機し（上限あり：指定された期限はローカルで120秒、リモートサーバーで55秒に制限されます）、OTP 文字列と信頼度、subject/from/id/received_at を返します。デフォルトでは since を省略し、この呼び出し以降に届いたメッセージのみが対象になります。
wait_for_link(inbox_id, timeout?=60, since?)	抽出されたマジックリンク（返されるだけで、アクセスはされません）と subject/from/id/received_at。デフォルトでは since を省略し、この呼び出し以降に届いたメッセージのみが対象になります。
list_inboxes(limit?, cursor?)	キーが所有する受信トレイの1ページ分（サーバーのデフォルトページサイズは25）と next_cursor/has_more
list_messages(inbox_id, has_otp?, subject_contains?, sender?, limit?, cursor?)	メッセージの1ページ分（任意でフィルタリング可能。サーバーのデフォルトページサイズは25）と next_cursor/has_more
get_latest(inbox_id)	待機せずに、最も新しいメッセージを取得します
send_test_code(inbox_id)	サンプル OTP メールを1通、メールサーバーを介さずに直接受信トレイに追加し、message_id と sent_at を返します。実際のメールを使わずに待機ループを確認できます。受信トレイごとに1時間あたり5回、アカウントごとに1時間あたり20回までです。
delete_inbox(inbox_id)	使用後に受信トレイを削除します

SDK のエラー（AuthError / NotFound / RateLimited / WaitTimeout）は、明確な MCP ツールエラーに変換されます。スタックトレースは表示されず、API キーが返されることもありません。

受信トレイの再利用

create_inbox では since は不要です。新しい受信トレイには、新しいメッセージしか届かないためです。デフォルトでは、wait_for_otp/wait_for_link は since を完全に省略するため、サーバーは呼び出し後（リクエスト開始時刻以降）に届いたメッセージのみを対象にします。ただし、既存の受信トレイを再利用する場合（例：2回目の OTP/リンクをリクエストする場合）は、since を明示的に渡してください。そうしないと、since を指定しない呼び出しでは、受信トレイにすでにあるメッセージは正しく無視されます。ほとんどの再利用ケースではこれで問題ありませんが、ツールを呼び出す前にすでに届いたコードを取得したい場合は、新しいメールをトリガーした直前の時刻（ISO8601 または Unix 秒）、または最後に確認したメッセージの id（msg_...。「そのメッセージより後のメッセージのみ」を意味します）のいずれかを渡してください。どちらのツールも、一致したメッセージの id/received_at を返すため、同じ受信トレイで次の呼び出しに since=<id> を渡して連携できます。

実際のメールを使わずにループを試す

send_test_code はメールサーバーを経由しないため、ツールが戻る時点ですでにコードは受信トレイにあります。まずカットオフを指定します。get_latest の id（受信トレイが空の場合は since=0）、または現在の時刻を使います。次に send_test_code(inbox_id) を呼び、その後 wait_for_otp(inbox_id, since=<that cutoff>) を呼び出します。since を指定しない場合、待機中に届いたメールのみが対象になるため、テストコードを取得できません。

必要条件

• Python 3.10+
• mailsocket API キー — ダッシュボードまたは POST /api/v1/agents/register から取得できます。

インストール

uv を使う場合、インストールは不要です。

uvx mailsocket-mcp

または pip でインストールします。

pip install mailsocket-mcp
mailsocket-mcp

どちらの場合も、環境変数から MAILSOCKET_API_KEY（および任意の MAILSOCKET_BASE_URL）を読み込みます。キーが設定されていない場合は、明確なメッセージを表示してステータス 2 で終了します。キーがログに記録されることはありません。

MCP クライアントへの登録

Claude Desktop / Cursor

クライアントの MCP 設定ファイルに以下を追加します。Claude Desktop の場合は claude_desktop_config.json、Cursor の場合は ~/.cursor/mcp.json です。

{
  "mcpServers": {
    "mailsocket": {
      "command": "uvx",
      "args": ["mailsocket-mcp"],
      "env": {
        "MAILSOCKET_API_KEY": "ms_live_..."
      }
    }
  }
}

Claude Code CLI

claude mcp add mailsocket -e MAILSOCKET_API_KEY=ms_live_... -- uvx mailsocket-mcp

ほかの MCP 互換クライアントでも同様に、stdio 経由で mailsocket-mcp 実行ファイル（または uvx mailsocket-mcp）を指定し、 環境変数を通じてキーを渡します。

リモートサーバー（インストール不要）

同じツールが Streamable HTTP 経由で https://mcp.mailsocket.app/mcp にホストされています。リクエストごとに、次のヘッダーでキーを送信してください。 Authorization: Bearer ms_live_...。キーを URL に含めないでください。?api_key= を使ったリクエストは拒否されます。

Claude Code CLI

claude mcp add --transport http mailsocket https://mcp.mailsocket.app/mcp \
  --header "Authorization: Bearer ms_live_..."

Cursor（~/.cursor/mcp.json）

{
  "mcpServers": {
    "mailsocket": {
      "url": "https://mcp.mailsocket.app/mcp",
      "headers": { "Authorization": "Bearer ms_live_..." }
    }
  }
}

VS Code（.vscode/mcp.json）

{
  "servers": {
    "mailsocket": {
      "type": "http",
      "url": "https://mcp.mailsocket.app/mcp",
      "headers": { "Authorization": "Bearer ms_live_..." }
    }
  }
}

カスタム HTTP ヘッダーを設定できるクライアントであれば、どれでも同様に利用できます（OpenAI Agents SDK、n8n MCP Client ノード、独自のコードなど）。

知っておくべきこと：

• Claude.ai、Claude Desktop コネクター、Smithery では OAuth が必要です。対応は予定されていますが、まだ利用できません。それまでは、これらのクライアント（Claude Desktop）では上記のローカル stdio サーバーを使用するか、ヘッダーを設定できるクライアントを使用してください。
• リモートサーバーでは、wait_for_otp / wait_for_link の待機時間は呼び出しごとに最大 55 秒です。これにより、各レスポンスがプロキシのタイムアウト時間内に収まります。タイムアウトした場合は、ツールを再度呼び出してください。
• サーバーはステートレスです。保持するセッションはなく、リクエストは毎回個別に認証されます。サーバー自体はキーを持たず、お客様のキーを使って、お客様の通常の API レート制限の範囲内でのみ動作します。
• セルフホスト：mailsocket-mcp-http は同じサーバーを実行します（環境変数については mailsocket_mcp/remote.py を参照してください）。

環境変数

変数	必須	説明
MAILSOCKET_API_KEY	はい（シークレット）	mailsocket API キー（ms_live_...）です。
MAILSOCKET_BASE_URL	いいえ	API のベース URL を上書きします。デフォルトは https://dash.mailsocket.app/api/v1 です。

開発

pip install -e ".[dev]"
pytest

テストでは、外部へのリクエストや実際の API へのリクエストは行いません。SDK クライアントは偽物を使用し、リモートトランスポートのテストは 127.0.0.1 上のローカルな偽アップストリームと通信します。

変更履歴

• 0.4.1 — mailsocket>=0.3.1 が必要です：since を指定せずに wait_for_otp / wait_for_link を呼び出した場合、SDK 内部のロングポーリング呼び出しの間に届いたメッセージを見落とさなくなりました（後続の呼び出しでは、サーバーが Mailsocket-Wait-Since で報告したカットオフが送信されます）。ツールのシグネチャに変更はありません。
• 0.4.0 — 新しい send_test_code(inbox_id) ツール（stdio とホストされたリモートサーバーで利用可能。他の待機を伴わないツールと同じキーごとの上限が適用されます）：メールサーバーを経由せず、自分の受信箱にサンプル OTP メールを 1 通送信します。mailsocket>=0.3.0（Client.send_test_code）が必要です。
• 0.3.0 — 動作変更（mailsocket>=0.2.0 によるもの）：wait_for_otp / wait_for_link は、デフォルトで since を 0（「受信箱にすでにあるすべてのメッセージ」）として渡すのではなく、省略するようになりました。以前のデフォルトでは、再利用した受信箱にすでに残っている古い OTP／リンクが返される可能性がありました。新しいデフォルトでは、呼び出し後に届いたメッセージのみが対象になります。以前の動作を維持するには、since=0 を明示的に渡してください。 ホストされたサーバー（mcp.mailsocket.app、リポジトリからデプロイ。新しい PyPI リリースはなし）：バックエンドの待機容量引き上げ（全体で 64）に伴い、キーごとの同時待機数を 3 から 10（Pro プランの上限。API は引き続き各プラン固有の上限を適用）に、共有待機プールを 16 から 32 に引き上げました。
• 0.2.3 — wait_for_otp / wait_for_link で since（ISO8601、unix 秒、またはメッセージ ID）を任意指定できるようになりました。再利用した受信箱から新しいコードを取得できます。結果にはメッセージの id と received_at が含まれます。
• 0.2.2 — mailsocket>=0.1.3 に依存します（基盤となる Python SDK で _seg ID の検証がより厳密になりました）。