lob-mcp

Lob.com API用のModel Context Protocolサーバーです。MCP対応のLLM（Claudeなど）から、Lobを通じて住所の確認や、ポストカード、手紙、セルフメーラー、印刷された小切手などの物理的な郵便物を送付できます。

⚠️ Lobは実際の物理的な郵便物を生成し、アカウントに課金します。 郵便物作成ツール（lob_postcards_create、lob_letters_create、lob_self_mailers_create、lob_checks_create、lob_*_orders_create）は課金対象です。開発には test_… で始まるAPIキーを使用してください。実際に郵便物を送る準備ができた場合にのみ live_… キーに切り替えてください。再試行時に重複して送付されないよう、必ず idempotency_key を渡してください。

機能

• 12のリソースグループにわたる76のツールで、Lob v1 APIの全機能をカバー：

  • アドレス帳 (CRUD)

  • 米国および国際的な住所確認（単一、一括、オートコンプリート、逆ジオコーディング、本人確認）

  • ポストカード、手紙、セルフメーラー、小切手（作成、一覧、取得、キャンセル）

  • テンプレートおよびテンプレートバージョン (CRUD)

  • キャンペーンおよびクリエイティブ (CRUD)

  • バックスリップ、カード、およびそれらの印刷注文

  • Informed Deliveryキャンペーン

  • QRコード分析

  • リソースプルーフ（送信前のプレビュー）

  • 銀行口座 (CRUD + マイクロデポジット確認)

  • USPS追跡イベント

  • Webhookサブスクリプション (CRUD)

• すべての課金対象作成エンドポイントでの**冪等性（Idempotency）**サポート

• APIキーのプレフィックスによるテスト/ライブモードの自動検出（起動時に表示）

• PII（個人識別情報）の秘匿化 — エラー出力から住所フィールドを削除

• すべての作成/更新ツールに汎用的な extra パラメータを搭載 — スキーマに列挙されていないLobのパラメータも受け入れ可能なため、SDKの更新遅延に阻まれることはありません

要件

• Node.js ≥ 18

• Lob APIキー — https://dashboard.lob.com/settings/api-keys から無料で取得可能

インストール

npxで実行（インストール不要）

npx lob-mcp

グローバルインストール

npm install -g lob-mcp
lob-mcp

ソースからインストール

git clone https://github.com/optimize-overseas/lob-mcp.git
cd lob-mcp
npm install
npm run build
node build/index.js

設定

サーバーの設定はすべて環境変数を通じて行います。

Claude Desktopでの使用

claude_desktop_config.json に以下を追加します：

{
  "mcpServers": {
    "lob": {
      "command": "npx",
      "args": ["-y", "lob-mcp"],
      "env": {
        "LOB_API_KEY": "test_your_key_here"
      }
    }
  }
}

Claude Desktopを再起動すると、ツールピッカーにLobのツールが表示されます。

Claude Codeでの使用

claude mcp add lob --env LOB_API_KEY=test_your_key_here -- npx -y lob-mcp

MCP Inspectorでの使用

npm run inspector

その後、ターミナルに表示されたURLを開きます。ツールを呼び出す前に、Inspectorの環境パネルで LOB_API_KEY を設定してください。

ツールリファレンス

すべてのツールは lob_<resource>_<action> という名前空間で管理されます。MCP仕様に従い、注釈ヒント（readOnlyHint、destructiveHint、idempotentHint、openWorldHint）が各ツールに設定されており、ホスト側で課金や破壊的な操作に対する適切な確認プロンプトを表示できます。

アドレス帳

• lob_addresses_create · lob_addresses_list · lob_addresses_get · lob_addresses_delete

住所確認

• lob_us_verifications_create · lob_us_verifications_get

• lob_us_autocompletions_create

• lob_intl_verifications_create

• lob_bulk_us_verifications_create · lob_bulk_intl_verifications_create

• lob_reverse_geocode

• lob_identity_validation

ポストカード（作成時に課金）

• lob_postcards_create · lob_postcards_list · lob_postcards_get · lob_postcards_cancel

手紙（作成時に課金）

• lob_letters_create · lob_letters_list · lob_letters_get · lob_letters_cancel

セルフメーラー（作成時に課金）

• lob_self_mailers_create · lob_self_mailers_list · lob_self_mailers_get · lob_self_mailers_cancel

小切手（作成時に課金 + 資金引き落とし）

• lob_checks_create · lob_checks_list · lob_checks_get · lob_checks_cancel

テンプレート

• lob_templates_create · lob_templates_list · lob_templates_get · lob_templates_update · lob_templates_delete

• lob_template_versions_create · lob_template_versions_list · lob_template_versions_get · lob_template_versions_update · lob_template_versions_delete

キャンペーン + クリエイティブ

• lob_campaigns_create · lob_campaigns_list · lob_campaigns_get · lob_campaigns_update · lob_campaigns_delete

• lob_creatives_create · lob_creatives_list · lob_creatives_get · lob_creatives_update · lob_creatives_delete

バックスリップ、カード、印刷注文（注文は課金対象）

• lob_buckslips_create · lob_buckslips_list · lob_buckslips_get

• lob_buckslip_orders_create · lob_buckslip_orders_list

• lob_cards_create · lob_cards_list · lob_cards_get

• lob_card_orders_create · lob_card_orders_list

Informed Delivery

• lob_informed_delivery_campaigns_create · lob_informed_delivery_campaigns_list · lob_informed_delivery_campaigns_get

QRコード + リソースプルーフ

• lob_qr_codes_list

• lob_resource_proofs_create · lob_resource_proofs_get · lob_resource_proofs_update

銀行口座（小切手の発行に必要）

• lob_bank_accounts_create · lob_bank_accounts_list · lob_bank_accounts_get · lob_bank_accounts_delete · lob_bank_accounts_verify

追跡イベント

• lob_tracking_events_list

Webhooks

• lob_webhooks_create · lob_webhooks_list · lob_webhooks_get · lob_webhooks_update · lob_webhooks_delete

安全モデル

このサーバーは、金銭が関わるAPIとして適切な3つの安全対策を強制します：

1. テスト/ライブモードの検出。 サーバーは起動時にAPIキーのプレフィックスを検査し、アクティブなモードをstderrにログ出力します。test_… キーでは実際の郵便物は生成されず、live_… キーでは実際の課金対象となる郵便物が生成されます。

2. 冪等性。 すべての課金対象作成ツールは、オプションの idempotency_key パラメータを公開しています。論理リクエストごとにUUID（または最大256文字のユニークな文字列）を渡してください。Lobは同じキーを再利用したリクエストに対して元のレスポンスを返すため、ネットワーク再試行による郵便物の重複送付を防ぎます。

3. エラー時のPII秘匿化。 クライアントに返されるエラーペイロードから、住所、氏名、連絡先フィールドが削除されます。リクエストボディ全体がログに記録されることはなく、エラーメタデータ（ステータス、コード、リクエストID、メッセージ）のみが表示されます。

extra エスケープハッチ

LobのAPIには、ツールスキーマに列挙するほどではないリソース固有のオプション（カスタム封筒ID、ミシン目ページ、請求グループ、マーケティングフラグなど）が多数あります。すべての作成/更新ツールはオプションの extra オブジェクトを受け入れ、そのキーはリクエストボディにそのままマージされます：

{
  "to": "adr_123…",
  "from": "adr_456…",
  "front": "<html>…</html>",
  "back": "<html>…</html>",
  "extra": {
    "billing_group_id": "bg_…",
    "use_type": "marketing"
  }
}

リソースごとのパラメータの詳細は https://docs.lob.com/ を参照してください。

開発

npm install
npm run build
npm run typecheck
npm run inspector

コンパイルされた出力は build/ に、ソースコードは src/ にあります。

アーキテクチャ

src/
├── index.ts            # stdio entry — boots McpServer + LobClient
├── env.ts              # env loading + test/live mode detection
├── lob/
│   ├── client.ts       # fetch-based HTTP client (Basic auth, idempotency, errors)
│   ├── errors.ts       # LobApiError + tool-friendly formatter
│   └── redact.ts       # PII redaction
├── schemas/
│   ├── common.ts       # address, pagination, idempotency, metadata schemas
│   └── mail.ts         # mail-piece-shared schemas
└── tools/
    ├── helpers.ts      # registerTool helper with consistent error mapping
    ├── register.ts     # wires every group into the server
    └── *.ts            # one file per resource group

HTTPクライアントは意図的に軽量に設計されています。公式の lob-typescript-sdk に依存しないことで、依存関係を最小限に抑え、ヘッダー、再試行、PII処理をサーバー側で厳密に制御できるようにしています。新しいLobエンドポイントは、リソースグループファイルにツールを登録する（または既存ツールの extra エスケープハッチを使用する）ことで追加可能です。

制限事項

• バイナリのPDF/画像バイトを受け入れるリソースのマルチパートファイルアップロードは、基盤となるクライアント（asForm: true）でサポートされていますが、ツールとしてはまだ公開されていません。現在のツールはHTML文字列、URL、テンプレートID、base64データURIを受け入れ、これらはLobがドキュメント化しているコンテンツソース形式をカバーしています。

• OAuth はLobが提供していないためサポートされていません。認証はLobのドキュメントに従い、APIキーを使用したHTTP Basic認証となります。

貢献

Issueやプルリクエストは https://github.com/optimize-overseas/lob-mcp で歓迎します。

ライセンス

MIT — LICENSE を参照してください。

免責事項

このプロジェクトはLob.comと提携、推奨、または後援を受けていません。「Lob」はLob.com, Inc.の商標です。Lob APIの使用は、Lobの利用規約および許容利用ポリシーに従うものとします。