postals-mcp

Postals

あらゆる AI をダイレクトメールマシンに変えるエージェントスキルです。 ツールを 1 回呼び出すだけ。本物の手書きポストカードを USPS でお届けします。

MCP 対応のあらゆる AI エージェントから、実物の手書きポストカードを送信できます — Claude Desktop、Cursor、Claude Code、OpenClaw、n8n、LangChain、CrewAI、または独自のコード。Postals が画像のアップロード、カードの作成、ロボットによる手書き（本物のペンとインク）、USPS での発送を処理します。

ウェブサイト：postals.ai

• 💌 1 枚あたり $4.99 — サブスクリプション不要、月間最低注文数なし
• ✍️ 本物の手書き — ロボットペンが本物のインクを使います（フォントによる再現ではありません）
• 📬 3～5 営業日 — 印刷後、USPS で発送します
• 🤖 エージェント向けに構築 — ツールを 1 回呼び出すだけ、支出制御、冪等性、テストモード
• 🌎 米国内および海外 — 世界中に配送。料金は配送先によって異なります

---

目次

• これが生まれた理由
• クイックスタート（5 分以内）
• クライアントの設定
• ツールのリファレンス
• プールビルダーのワークフロー
• メッセージの生成
• 画像の処理
• テストモード
• 支出制御
• エラー処理
• 設定リファレンス
• 手書きスタイル
• トラブルシューティング
• FAQ
• 今後の予定（ロードマップ）
• コントリビューション
• ライセンス

---

これが生まれた理由

AI エージェントのエコシステムでは、新しいパターンが現れています。世界（衛星画像、ソーシャルメディア、公開記録）を自律的にスキャンし、ビジネス機会を見つけ、実物の郵便物でアプローチするボットです。プール施工業者、造園業者、屋根工事業者、太陽光発電設備の設置業者、不動産業者は、ボットが送ったポストカードから、数万ドル、数十万ドル規模の契約を獲得しています。

Postals が登場する前は、施工業者がそれぞれ独自の郵送システムを一から構築していました。画像のアップロード、カードのテンプレート作成、印刷 API、住所の検証、USPS への引き渡し、追跡などです。構築には何週間もかかり、壊れやすいものでした。

これらを1 つのツールとして提供します。エージェントは、宛先とメッセージを指定して send_postcard を呼び出します。あとは私たちが処理します。

---

クイックスタート

1. サインアップして API キーを取得する

近日公開 — postals.ai/developers の開発者ポータルはまもなく開始します。 公開後の手順は次のとおりです。

1. postals.ai/developers にアクセスします
2. メールアドレスでアカウントを作成します（ワンクリックのマジックリンク方式 — パスワード不要）
3. ウォレットに入金します（Stripe または暗号資産で $25 / $50 / $100 / $250）
4. postals_live_ API キーをコピーします
5. MCP 設定に貼り付けます（下のステップ 2 を参照）

これで完了です。外部アカウントは必要ありません。Postals だけで使えます。

2. MCP クライアントにサーバーを追加する

オプション A — コーディングエージェントにインストールを依頼する（最も簡単な方法）

Claude Code、Cursor、Continue、Aider、またはファイルシステムにアクセスできるその他の MCP クライアントを使っている場合は、エージェントに次のように伝えるだけです。

このクライアントに postals-mcp MCP サーバーをインストールしてください。Postals API キーは PASTE_YOUR_KEY_HERE です。実際のカードを送る前に設定を確認できるよう、テストモードで開始してください。

エージェントが MCP 設定ファイルを見つけ、既存の mcpServers に postals エントリを追加し（既存の他のサーバーはそのまま保持します）、環境変数を設定して、クライアントを再起動するよう案内します。JSON を自分で編集する必要はありません。

任意 — 同じプロンプトに返送先の詳細を追加すると、send_postcard を呼び出すたびに指定しなくても使えるようになります。

...返送先住所には Jane Smith、123 Main St、Austin TX 78701 を使用してください。

その後、クライアントを完全に終了して再起動してください（macOS では Cmd+Q を使用します — ウィンドウを閉じるだけでは不十分です）。

オプション B — MCP 設定ファイルを直接編集する

Claude Desktop（デフォルトではファイルシステムへのアクセス機能が組み込まれていません）や、手動で設定したいクライアントの場合は、~/Library/Application Support/Claude/claude_desktop_config.json（macOS）または %APPDATA%\Claude\claude_desktop_config.json（Windows）を編集します。

{
  "mcpServers": {
    "postals": {
      "command": "npx",
      "args": ["-y", "postals-mcp"],
      "env": {
        "POSTALS_API_KEY": "your_api_key",
        "POSTALS_SENDER_NAME": "Jane Smith",
        "POSTALS_SENDER_ADDRESS": "123 Main St",
        "POSTALS_SENDER_CITY": "Austin",
        "POSTALS_SENDER_STATE": "TX",
        "POSTALS_SENDER_ZIP": "78701",
        "POSTALS_TEST_MODE": "true"
      }
    }
  }
}

ほかのクライアント（Cursor、Claude Code、OpenClaw）の設定は、以下のクライアント設定セクションをご覧ください。

編集後、クライアントを完全に再起動してください。（ウィンドウを閉じるだけではなく、メニューから終了してください。）

3. 動作を確認する

新しいチャットを開き、次のように尋ねます。

"利用可能なMCPツールを一覧表示してください。"

send_postcard と generate_message が表示されるはずです。

4. テストカードを送る

テストモード（POSTALS_TEST_MODE=true）のまま、次のように尋ねます。

"Jane Smith（住所：123 Oak St, Austin TX 78701）に、「昨日は素晴らしいミーティングをありがとうございました。次のステップを楽しみにしています。」というメッセージを添えて、ポストカードを送ってください。"

エージェントが send_postcard を呼び出します。モックの order_id と、テストモードが有効であることを示す確認が返されます。カードは郵送されず、料金も発生しません。

5. 本番運用を開始する

設定から POSTALS_TEST_MODE を削除する（または false に設定する）と、再起動後の次回送信で実際のカードが郵送されます。

---

クライアント設定

主要なMCPクライアントすべてに対応した、コピーしてすぐに使える設定です。Claude Code、Cursor、Continue、Aiderをお使いの場合、このセクションはスキップできます。エージェントにPostalsのインストールを指示するだけです（クイックスタートのオプション Aを参照）。設定はエージェントが行います。

Claude Desktop

~/Library/Application Support/Claude/claude_desktop_config.json（macOS） %APPDATA%\Claude\claude_desktop_config.json（Windows）

{
  "mcpServers": {
    "postals": {
      "command": "npx",
      "args": ["-y", "postals-mcp"],
      "env": {
        "POSTALS_API_KEY": "your_key"
      }
    }
  }
}

Cursor

グローバル：~/.cursor/mcp.json プロジェクトごと：リポジトリのルートにある .cursor/mcp.json

{
  "mcpServers": {
    "postals": {
      "command": "npx",
      "args": ["-y", "postals-mcp"],
      "env": {
        "POSTALS_API_KEY": "your_key"
      }
    }
  }
}

Claude Code

claude mcp add postals npx -y postals-mcp

次に、~/.claude/settings.json の mcpServers.postals.env に環境変数を設定します。

OpenClaw / InstaClaw

エージェント向けスキル定義の全容については、同梱の SKILL.md をご覧ください。単独でOpenClawを使用する場合：

mcp_servers:
  postals:
    command: npx
    args: ["-y", "postals-mcp"]
    env:
      POSTALS_API_KEY: ${POSTALS_API_KEY}

n8n（Composio経由 — v1.1以降）

ComposioマーケットプレイスからPostalsツールキットをインストールします。ワンクリックで任意のワークフローに追加できます。利用可能になったら、Composioのドキュメントをご覧ください。

カスタムエージェント（プログラムでの利用）

任意のMCPクライアントライブラリを使用できます。公式TypeScript SDKを使った例：

import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";

const transport = new StdioClientTransport({
  command: "npx",
  args: ["-y", "postals-mcp"],
  env: { POSTALS_API_KEY: "your_key", POSTALS_TEST_MODE: "true" },
});
const client = new Client({ name: "my-agent", version: "1.0" }, { capabilities: {} });
await client.connect(transport);

const result = await client.callTool({
  name: "send_postcard",
  arguments: {
    to_name: "John Smith",
    to_address: "123 Oak St",
    to_city: "Austin",
    to_state: "TX",
    to_zip: "78701",
    message: "Hey John — thought you'd love this.",
    front_image_url: "https://example.com/render.png",
    idempotency_key: "john-smith-123-oak-001",
  },
});

---

ツールリファレンス

send_postcard

米国内の住所宛てに、手書きの物理的なポストカードを1枚郵送します。

入力

フィールド	型	必須	説明
to_name	string	✓	受取人の氏名
to_address	string	✓	住所の1行目
to_address_2	string		アパート／スイート／ユニット
to_city	string	✓	市区町村
to_state	string	✓	2文字の米国州コード
to_zip	string	✓	5桁のZIPコード（または5桁＋4桁）
message	string	✓	手書きメッセージ（最大400文字）
front_image_url	string		カード表面画像（PNG/JPEG）のHTTPS URL。指定がない場合は POSTALS_DEFAULT_CARD_IMAGE が使用されます。
handwriting_style	string		フォント名。デフォルト：Joyful Jennifer
return_address	object		呼び出しごとの差出人情報の上書き。指定がない場合は POSTALS_SENDER_* 環境変数が使用されます。
idempotency_key	string		重複排除用の一意なキー。同じキーを使うと同じ結果が返され、重複送信されません。有効期間は24時間です。

出力（成功時）

{
  "success": true,
  "order_id": 196937,
  "card_id": 305570,
  "recipient": "John Smith",
  "estimated_delivery": "3-5 business days via USPS",
  "balance_remaining": -1,
  "cards_available": -1,
  "cards_sent_today": 7,
  "daily_limit": 25
}

postals.ai/developersの postals_live_ APIキーを使用すると、balance_remaining と cards_available に実際の値が返されます。

**出力（テストモード時）**には test_mode: true と mock_order_id が追加されます。カードは郵送されません。

**出力（エラー時）**は、実行可能な対処方法を示すメッセージとともに isError: true を返します。エラー処理をご覧ください。

generate_message

パーソナライズされたポストカードのメッセージを AI が下書きします。設定されている場合は Cloudflare AI を使用し、そうでない場合は、エージェントが独自に生成するために使える構造化プロンプトを返します（エージェントはすでに LLM なので、多くの場合、これで十分な品質が得られます）。

入力

フィールド	型	必須	説明
recipient_context	string	✓	受取人が誰で、なぜメッセージを書くのか
tone	enum		warm（デフォルト）、professional、casual、excited
max_chars	number		メッセージの最大文字数。デフォルトは350、最大は400です。
sender_context	string		送信者が誰か

出力（AI 設定済み）

{
  "message": "Hey John — drove by your place on Oak St and couldn't help but picture how a pool would transform that backyard. Happy to share a quick render if you're curious. — Kevin, Blue Wave Pools",
  "char_count": 212,
  "tone": "warm",
  "ai_generated": true
}

出力（AI 未設定） — エージェント自身の LLM に入力できるシステムプロンプトとユーザープロンプトを返します。

{
  "message": null,
  "ai_generated": false,
  "prompt": {
    "system": "You write short, personal messages for physical handwritten postcards...",
    "user": "Recipient: John Smith, homeowner at 123 Oak St...\nSender: Blue Wave Pools\n\nWrite the postcard message now."
  },
  "instructions": "Cloudflare AI not configured. Use the system/user prompts above to generate the message...",
  "tone": "warm",
  "max_chars": 350
}

compose_postcard_message（MCP プロンプト）

MCP プロンプトのプリミティブ（ツールではありません）です。エージェントが自身の LLM で使用できる、書式設定済みのプロンプトテンプレートを返します。外部 API への依存はありません。決定的で、依存関係のないメッセージ作成が必要な場合に便利です。

引数： recipient、sender（任意）、tone（任意）。

---

プール施工業者向けワークフロー

これは、自律的なポストカード送付を広く知らしめた、話題性の高いユースケースです。プール施工業者は、次の処理を行うエージェントを運用します。

1. スキャン — 近隣地域の衛星画像を確認します（Google Maps、Nearmap など）。
2. 分類 — プールのない家を見つけます。
3. レンダリング — その家の実際の裏庭にプールを設置した、パーソナライズされたビフォーアフター画像を生成します。
4. 作成 — その家に合わせた、温かみのある具体的なメッセージを書きます。
5. 送付 — 手書きのポストカードを郵送します。
6. 成約 — 週ごとに数万ドル規模の契約が成立します。

Postals が担うのは、ツールを2回呼び出すステップ4～5です。ステップ1～3はご自身で行います（どのような画像パイプラインでも利用できます）。

完全な例

// Your pipeline produced:
//   - homeowner: { name, street, city, state, zip }
//   - renderUrl: "https://cdn.mybucket.com/renders/123-oak-st-pool.jpg"

const msg = await generate_message({
  recipient_context: `${homeowner.name}, homeowner at ${homeowner.street}. Corner lot with large flat backyard, no pool.`,
  sender_context: "Blue Wave Pools — Austin, TX. Specializing in fiberglass pools installed in 14 days.",
  tone: "warm",
});

const result = await send_postcard({
  to_name: homeowner.name,
  to_address: homeowner.street,
  to_city: homeowner.city,
  to_state: homeowner.state,
  to_zip: homeowner.zip,
  message: msg.message,
  front_image_url: renderUrl,
  idempotency_key: `prospect-${homeowner.id}`,  // crucial for retries
});

console.log(`Mailed card ${result.order_id}. ${result.cards_sent_today}/${result.daily_limit} today.`);

効果がある理由

• 本物の手書き文字は、開封率で印刷郵便を5～10倍上回ります。
• 極めてパーソナライズされた画像（相手の実際の家です！）は、無視できない印象を与えます。
• 温かみのある具体的なメッセージは、人間らしく感じられ、一斉送信のような印象になりません。
• USPS による配達は、「これは重要だ」という意識を呼び起こします。

バリエーション

業種	スキャン対象	レンダリング	トーン
プール施工業者	裏庭にプールがない家	庭にプールを設置した画像	温かみがあり、夢を感じさせる
造園業者	荒れた庭、枯れた庭	手入れの行き届いた景観	温かみがあり、視覚的
屋根工事業者	損傷または老朽化した屋根	新しい屋根の画像	専門的で、緊急性のある
太陽光発電設置業者	南向きの広い屋根	ソーラーパネルの画像	専門的で、節約効果を重視
不動産業者	FSBO または掲載期限切れの物件	家具を配置した室内の画像	専門的で、親切な
住宅リフォーム業者	古びた外観	現代風に改装した画像	高揚感があり、大きな変化を感じさせる

どのケースでも同じ2回のツール呼び出しを使います。異なるのはスキャン、レンダリング、トーン、メッセージだけです。

---

メッセージの生成

手書きメッセージを作成する方法は3つあります。セットアップに応じて選んでください。

オプション A — Cloudflare AI を使う generate_message ツール

CLOUDFLARE_ACCOUNT_ID と CLOUDFLARE_API_TOKEN を設定します。サーバーは Cloudflare Workers AI 経由で Llama 3.1 8B Instruct を呼び出し、実績のある Postals のトーンプロファイルを使用します。そのまま使えるメッセージを返します。

"env": {
  "POSTALS_API_KEY": "...",
  "CLOUDFLARE_ACCOUNT_ID": "...",
  "CLOUDFLARE_API_TOKEN": "..."
}

オプション B — AI を使わない generate_message ツール（ほとんどのエージェントにおすすめ）

CF 変数を設定しないでください。このツールは構造化プロンプト（システムプロンプトとユーザープロンプト）を返し、エージェントは自身の LLM でそれを使います。呼び出し元のエージェントはすでに LLM（Claude、GPT など）なので、Llama 3.1 と同等以上、多くの場合はそれ以上のメッセージを生成できます。

オプション C — compose_postcard_message MCP プロンプト

MCP プロンプトのプリミティブ（ツールではありません）です。Claude Desktop ではスラッシュコマンドメニューに表示されます。エージェントは Postals のガイドラインを直接コンテキストに取り込み、メッセージを作成します。

オプション D — エージェントがメッセージを自分で書く

generate_message を完全に省略します。エージェントはすでに文章を作成できます。send_postcard にメッセージを直接渡してください。

---

画像の取り扱い

front_image_url は、PNG または JPEG の公開 HTTPS URLである必要があります。サーバーが画像を取得して印刷パートナーにアップロードし、カスタムカードを作成します。

推奨仕様

• 形式： PNG または JPEG
• 向き： 横向き（縦より横が長い）
• サイズ： 2100 × 1500 px（300 DPI で 7×5 インチ）— 印刷品質
• 最小サイズ： 1050 × 750 px
• 最大ファイルサイズ： 10 MB
• アクセス可能性： 公開 URL、認証ヘッダーなし、有効期間の短い署名付き URL は不可

一般的なソース

ソース	例
独自の CDN / S3 / Cloudflare R2	https://cdn.yoursite.com/renders/xyz.png
AI 画像生成の出力	ほとんどのサービスは公開 URL を返します
静的テンプレート	サイトでホストされている、事前にデザインされた会社のカード
Recraft V3（今後のリリースで提供予定）	generate_card_image ツールが URL を返します

画像がない場合

POSTALS_DEFAULT_CARD_IMAGE にブランドのフォールバック画像を設定してください。front_image_url を指定しないすべての呼び出しで、デフォルト画像が使われます。すべてのカードで同じテンプレートを使うビジネス用途に最適です。

---

テストモード

コストもリスクもゼロでテストできます。環境変数に POSTALS_TEST_MODE=true を設定してください。

有効にすると：

• すべての入力が通常どおり検証されます（州コード、ZIP 形式、メッセージの長さ、HTTPS URL）
• 1 日あたりの上限カウンターが増加します（支出制御をテストできます）
• レートリミッターによって 2 秒の待機時間が適用されます（タイミングをテストできます）
• フルフィルメント API は呼び出されません — カードは印刷されず、費用も発生しません
• レスポンスには test_mode: true と mock_order_id が含まれます

{
  "success": true,
  "test_mode": true,
  "message": "Test mode — no card sent. Set POSTALS_TEST_MODE=false to send real cards.",
  "mock_order_id": "test-1713099999999",
  "recipient": "Jane Smith",
  "estimated_delivery": "3-5 business days via USPS",
  "cards_sent_today": 3,
  "daily_limit": 25
}

推奨事項： まず POSTALS_TEST_MODE=true に設定し、エージェントのツール呼び出しが正しいことを確認してから、最初の実際の送信に向けて無効にしてください。

---

支出制御

エージェントは自律的に実行されます。不適切な設定に上限が加わらないと、高額なバグにつながります。このサーバーには、4 つの安全対策が備わっています。

1. 1 日あたりの上限（POSTALS_DAILY_LIMIT、デフォルトは 50）

1 日あたりのカード枚数の上限です。カウンターは UTC の午前 0 時にリセットされます。上限に達すると：

isError: true
"Daily limit reached (25/25). Resets at midnight UTC. Adjust with POSTALS_DAILY_LIMIT env var."

開発中は少ない値（5～10）に設定してください。エージェントの動作が確認できたら、上限を引き上げます。

2. レートリミッター（送信間隔の最小値は 2 秒）

サーバー側で確実にスロットルします。send_postcard を短時間に 2 回呼び出すと、2 回目の呼び出しは実行前に 2 秒待機します。API の悪用を防ぎ、制御不能な動作に気づく時間を確保します。

3. 冪等性キー

send_postcard の引数に idempotency_key を渡します。同じキーなら同じ結果となり、重複送信されません。キーは 24 時間キャッシュされます。

await send_postcard({ ..., idempotency_key: "prospect-123-oak-st" });
// If the network hiccups and your agent retries with the same key,
// you get back the original response — no second card mailed.

自律型エージェントには不可欠です。 これがないと、ネットワークタイムアウト後に再試行した場合、ハガキが 2 通送られることがあります。

4. テストモード

上記を参照してください。開発中は、念には念を入れて利用してください。

v1.1 で提供予定

プリペイドウォレット（前払いして残高から支出）とカードごとの請求、月間上限付きの自動チャージ、3 つの入金方法（Stripe、USDC/WLD 暗号資産、エージェントによる自己資金調達）、即時一時停止（ダッシュボードから API キーを無効化）、さらにエージェントが自身の支出を調整できるよう、すべてのレスポンスで残高を追跡できる機能。

---

エラー処理

エラーは isError: true と、エージェントが人間に伝えられるように書かれた、対処方法がわかるメッセージを返します。例：

シナリオ	エラーメッセージ
API キーがない	"POSTALS_API_KEY not set. Add it to your MCP server env config. Get a key at postals.ai/developers."
無効な州コード	"Invalid state code \"ZZ\". Must be a 2-letter US state (e.g. CA, NY, TX)."
無効な ZIP コード	"Invalid ZIP \"ABC12\". Must be 5 digits (e.g. 78701) or 5+4 (e.g. 78701-1234)."
画像がなく、デフォルトも設定されていない	"No card image. Provide front_image_url or set POSTALS_DEFAULT_CARD_IMAGE env var."
HTTPS ではない画像 URL	"front_image_url must be an HTTPS URL."
差出人住所がない	"No return address. Provide return_address or set POSTALS_SENDER_* env vars."
1 日の上限に到達	"Daily limit reached (25/25). Resets at midnight UTC. Adjust with POSTALS_DAILY_LIMIT env var."
画像の取得に失敗	"Send failed: Cannot fetch image from URL (HTTP 404). Ensure the URL is publicly accessible."
発送処理エラー	"Send failed: <classified error — address, message length, auth, etc.>"

エラーメッセージは、エージェントが内容を読み取って自ら修正するか、平易な言葉で修正方法を人間に伝えられるように設計されています。

---

設定リファレンス

すべての設定は、MCP クライアントの設定にある環境変数で指定します。

変数	必須	デフォルト	説明
POSTALS_API_KEY	はい	—	postals.ai/developers で取得した API キーです。
POSTALS_SENDER_NAME	推奨	—	デフォルトの差出人氏名
POSTALS_SENDER_ADDRESS	推奨	—	デフォルトの差出人住所
POSTALS_SENDER_CITY	推奨	—	デフォルトの差出人の市区町村
POSTALS_SENDER_STATE	推奨	—	デフォルトの差出人の 2 文字の州コード
POSTALS_SENDER_ZIP	推奨	—	デフォルトの差出人の ZIP コード
POSTALS_DEFAULT_CARD_IMAGE	推奨	—	デフォルトのカード表面画像の HTTPS URL（呼び出し元が front_image_url を省略した場合に使用）
POSTALS_HANDWRITING_STYLE	任意	Joyful Jennifer	デフォルトの手書きフォント
POSTALS_DAILY_LIMIT	任意	50	1 日あたりのカード送信上限です。開発中は低い値に設定してください。
POSTALS_TEST_MODE	任意	false	true = 実際の送信をスキップし、モックのレスポンスを返します
CLOUDFLARE_ACCOUNT_ID	任意	—	Llama 3.1 による AI メッセージ生成を有効にします
CLOUDFLARE_API_TOKEN	任意	—	CLOUDFLARE_ACCOUNT_ID と併せて必要です

呼び出しごとの上書き： send_postcard の引数に指定した return_address、handwriting_style、front_image_url は、その送信に限り環境変数のデフォルト値を上書きします。

---

手書きスタイル

デフォルト：Joyful Jennifer — 温かく、親しみやすい、自然な手書き文字です。

よく使われる手書きスタイルのオプション：

• Joyful Jennifer — 温かく、親しみやすい女性的な書体
• Tarzan — 太く、エネルギッシュ
• Casual Craig — リラックスした男性的な書体
• Fancy Fiona — エレガントな筆記体
• Precise Paul — 整然とした、ビジネス向けの書体

ツールの引数で handwriting_style に正確なスタイル名を渡すか、POSTALS_HANDWRITING_STYLE を全体設定として指定してください。アカウントで利用できるすべてのスタイルを確認するには、postals.ai/developers で利用可能なスタイルを参照してください。

---

トラブルシューティング

Claude Desktop にツールが表示されない

1. Claude Desktop を完全に終了（ウィンドウを閉じるだけではなく、メニューから［終了］を選択）して、再起動してください。設定の変更を反映するには、完全な再起動が必要です。
2. 設定 JSON が有効であることを確認してください（末尾のカンマがないこと、引用符が正しいこと）。
3. macOS では、パスを確認してください：~/Library/Application\ Support/Claude/claude_desktop_config.json。
4. ターミナルで npx -y postals-mcp を手動で実行してください。エラーが発生する場合は、まずその問題を修正してください。

npx -y postals-mcp が応答しない

これは想定どおりの動作です。標準入力で MCP プロトコルの入力を待っています。単体でテストするには、付属のテストハーネスを使用してください。

cd src/MCP/postals-mcp
npm install
npm run build
POSTALS_API_KEY=test POSTALS_TEST_MODE=true node test-harness.mjs

「POSTALS_API_KEY not set」

環境変数がサーバーに渡されていません。次の点を確認してください。

• MCP クライアントの設定で、env ブロックが正しく設定されている
• 設定を編集した後、クライアントを再起動した
• JSON 内でキーが引用符で囲まれている

「Cannot fetch image from URL」

画像 URL は次の条件を満たす必要があります。

• 公開 HTTPS URL である（http://、file://、data: は不可）
• 認証ヘッダーや Cookie なしでアクセスできる
• Content-Type: image/png または image/jpeg を指定して、有効な PNG または JPEG を返す

curl -I <url> でテストしてください。200 と有効な画像の Content-Type が返る必要があります。

カードが届かない

1. POSTALS_TEST_MODE が true に設定されていますか？ 設定されている場合、カードは実際には郵送されません。削除するか、false に設定してください。
2. 呼び出しから返された order_id について、postals.ai/developers で注文状況を確認してください。
3. 配達には、カードが注文された日ではなく、郵送された日から3～5営業日かかります。印刷は1営業日以内に行われます。

レート制限が遅すぎるように感じる

最低2秒という制限は意図的に設けられており、変更できません。API の不正利用を防ぎ、制御不能な動作に気付けるようにするためです。

---

よくある質問

費用はいくらですか？ カード1枚あたり4.99ドルです。月間最低利用数やサブスクリプションはありません。月101枚から数量割引があります（v1.1）。

どのくらいで届きますか？ 発送後、USPS経由で3～5営業日です。API呼び出しから1営業日以内にカードを印刷して発送します。

本当に手書きですか？ はい。専用に開発されたロボットが本物のペンを持ち、本物のインクで本物の紙に書きます。受取人にはロボットが書いたとはわかりません。

手書きの郵便物の開封率はどのくらいですか？ 印刷されたダイレクトメールと比べて、通常5～10倍高くなります。表面にパーソナライズされた画像（AI生成）を使うと、反応率がさらに上がります。

どの国に対応していますか？ 米国内の住所への発送はカード1枚あたり4.99ドルで、USPS経由で3～5営業日で届きます。海外の住所にも対応しています。配達にはさらに時間がかかり、料金は配送先によって異なります。海外向けの料金についてはお問い合わせください。

手紙や荷物を送れますか？ v1.0ではハガキのみです。手紙、封筒、グリーティングカードは今後のリリースで対応予定です。

対応している画像形式は何ですか？ PNGまたはJPEGです。横向きの7×5インチ（300 DPIで2100×1500 px）が理想的です。

送信をキャンセルできますか？ v1.0ではできません。印刷中のキャンセル（cancel_postcard ツール）はv1.1で対応予定です。

配達状況を確認できますか？ v1.0ではできません。check_order_status ツールはv1.1で対応予定です。

エージェントにバグがあり、カードを1000枚送ろうとした場合はどうなりますか？ 開発中は POSTALS_DAILY_LIMIT を低め（5～10）に設定してください。11枚目の送信では、発送される代わりにエラーが返されます。再試行時の idempotency_key と2秒間のレート制限を組み合わせることで、よくある暴走シナリオの上位3つに対処できます。v1.1では、残高に上限を設けたウォレットが追加されます。残高が0ドルになると、エージェントは停止します。

エージェントは暗号資産の収益で自分の資金を調達できますか？ v1.1で対応予定です。資金調達方法は3つあります。Stripe（人間が支払う）、暗号資産の入金（人間がUSDC/WLDを送金する）、エージェントによる自己資金調達（エージェントが自身のウォレットから支出する。人間の承認が必要で、月間上限を設定可能）です。これにより、エージェントが暗号資産を獲得し、ウォレットに入金し、カードを送り、取引を成立させ、さらに収益を得るという、完全に自律したビジネスのサイクルを実現できます。

商用利用できますか？ はい。MITライセンスです。カードは送信ごとの課金で、ライセンス料はありません。

LobやPostGridと比べて、料金はどうですか？ LobとPostGridでは、印刷されたハガキを0.48～0.77ドルで提供しています。当社は手書きのハガキを4.99ドルで提供しています。別の商品です。この手書きのプレミアム料金は、効果が重要となる種類のアウトバウンド用途（不動産、住宅サービス、高額商品の販売など）で、開封率と反応率が大幅に高まるため、十分に回収できます。

複数のエージェントで1つのAPIキーを共有できますか？ はい。ただし、日次上限も共有されます。エージェントごとにキーを分けて、個別に管理してください（v1.1以降では、1つのアカウントで複数のキーを利用できます）。

langchain／crewai／autogenでも使えますか？ MCP クライアントに対応したフレームワークであれば、どれでも使えます。TypeScript／Python MCP SDKは、ほかのMCPツールと同じようにこのサーバーへ接続します。コードについては、カスタムエージェントのセクションをご覧ください。

どのようなデータをログに記録しますか？ 構造化されたJSONイベントをstderrのみに記録します。記録するのは、イベント名、タイムスタンプ、都市／州（デバッグ用）、カウンター値、注文IDです。**記録することはありません：**完全な住所、メッセージ全文、受取人の名前、APIキー、認証トークンを含む画像URL。

---

今後の予定

現在：v1.0 — 1枚あたり$4.99。

v1.1 で登場予定（2～3週間後）：

• postals.ai/developers での開発者登録
• Stripe + USDC 暗号資産によるプリペイドウォレット（事前に支払い、残高から利用）
• check_balance ツール — エージェントがすべてのレスポンスで残高を確認
• check_order_status ツール — 発送状況をポーリング
• cancel_postcard ツール — 印刷期間内のキャンセル
• 外部アカウント不要

v2.0 で登場予定（6～8週間後）：

• postals.ai/developers に開発者向けダッシュボードを全面展開
• 月額上限付きの自動チャージ
• Webhook イベント（card_sent、low_balance、daily_limit_hit）
• アカウントごとに複数の API キー
• パス3： エージェント自身の暗号資産ウォレットからの自己資金調達（人間の承認が必要）
• USPS CASS 認定の住所検証
• ボリューム別料金プラン（101～500：$4.49、501～2000：$3.99、2000以上：要相談）

v3.0 以降で登場予定：

• generate_card_image ツール — Recraft V3 AI によるカードアート
• カードテンプレートライブラリ（お礼、誕生日、ビジネス、不動産など）
• 複数のフルフィルメントプロバイダー（手書きと印刷のオプション）
• 国際郵便（カナダ、英国、EU）
• 大量送信ワークフロー向けの一括送信ツール
• 手紙と封筒

ロードマップとアーキテクチャの詳細はpostals.aiをご覧ください。

---

コントリビューション

GitHub リポジトリへの Issue と PR を歓迎します。大きな変更の場合は、まず Issue を作成して相談してください。

テストハーネスの実行：

npm install
npm run build
POSTALS_API_KEY=test POSTALS_TEST_MODE=true node test-harness.mjs

37 件すべてのチェックが成功するはずです。

---

リンク

• ウェブサイト： postals.ai
• npm： postals-mcp
• GitHub： github.com/coopergwrenn/postals-mcp
• agents.md（エージェント向け）：postals.ai/agents.md
• SKILL.md（同梱のスキルファイル）：./SKILL.md
• Model Context Protocol： modelcontextprotocol.io

---

ライセンス

MIT © Postals