Solmail MCP

🚀 SolMail MCPサーバー

AIエージェントからSolana暗号通貨を使って実際の物理的な郵便を送ることができます。

SolMail MCPは、ClaudeなどのAIエージェントが世界中の実際の住所に物理的な手紙やはがきを送ることを可能にするModel Context Protocol (MCP)サーバーです。支払いはSolana (SOL)暗号通貨で行われます。物理世界とのやり取りが必要なエージェントに最適です。

🏆 コロシアムエージェントハッカソン向けに開発 ✅ 本番環境での使用可能 - 簡単な設定変更でテストモードから本番モードに切り替え可能 🧪 デモモード - devnetのSOLとLobのテストAPIを使ってテストできます（実際の料金はかかりません） 🚀 本番モード - メインネットのSOLを使って実際の郵便を配達します

✨ 主な機能

• 📬 実際の郵便を送信: 物理的な手紙を印刷し、任意の住所に郵送します
• 💰 暗号通貨による支払い: Solana (devnetまたはメインネット) のSOLで支払います
• 🌍 世界中への配達: 200以上の国に送ることができます
• 🤖 AIネイティブ: AIエージェントとの統合を目的として構築されています
• ⚡ 高速かつ安価: Solanaのサブ秒単位の最終性と約$0.00025のトランザクション手数料
• 🔒 非管理型: 直接ウォレットを制御し、仲介者は必要ありません

📦 インストール

# プロジェクトをクローンまたは作成
git clone <repository-url>
cd solmail-mcp

# 依存関係をインストール
npm install

# TypeScriptコードをビルド
npm run build

💻 使用例

基本的な使用法

# このMCPサーバーを使用するには、AIエージェントに独自のSolanaウォレットが必要です。
# Solana CLIをインストール（まだインストールされていない場合）
sh -c "$(curl -sSfL https://release.solana.com/stable/install)"

# 新しいキーペアを生成
solana-keygen new --outfile ~/.config/solana/agent-wallet.json

# base58形式の秘密鍵を取得
solana-keygen pubkey ~/.config/solana/agent-wallet.json  # これがあなたの公開アドレスです

# .envファイルに使用するためのbase58形式の秘密鍵を取得するには：
# キーペアJSONファイルには秘密鍵のバイト列が含まれています

高度な使用法

{
  "mcpServers": {
    "solmail": {
      "command": "node",
      "args": ["/absolute/path/to/solmail-mcp/dist/index.js"],
      "env": {
        "SOLMAIL_API_URL": "https://solmail.online/api",
        "SOLANA_NETWORK": "devnet",
        "SOLANA_PRIVATE_KEY": "your_base58_private_key"
      }
    }
  }
}

上記の設定をClaude DesktopのMCP設定ファイルに追加し、Claude Desktopを再起動します。

📚 ドキュメント

利用可能なツール

get_mail_quote

郵便を送るための見積もりを取得します。 入力:

{
  "country": "US",
  "color": false
}

出力:

{
  "priceUsd": 1.50,
  "priceSol": 0.015,
  "solPrice": 100.0,
  "breakdown": {
    "basePrice": 1.50,
    "colorPrinting": 0.00
  },
  "country": "US",
  "estimatedDelivery": "3-5 business days"
}

send_mail

Solana支払いで物理的な郵便を送ります。 入力:

{
  "content": "Dear Friend,\n\nThis letter was sent by an AI agent using Solana cryptocurrency!\n\nBest regards,\nClaude",
  "recipient": {
    "name": "John Doe",
    "addressLine1": "123 Main Street",
    "city": "San Francisco",
    "state": "CA",
    "zipCode": "94102",
    "country": "US"
  },
  "mailOptions": {
    "color": false,
    "doubleSided": false,
    "mailClass": "first_class"
  }
}

出力:

{
  "success": true,
  "letterId": "ltr_abc123",
  "trackingNumber": "9400000000000000000000",
  "expectedDeliveryDate": "2026-02-07T00:00:00Z",
  "previewUrl": "https://...",
  "payment": {
    "signature": "5j7s...",
    "amount": 0.015,
    "priceUsd": 1.50
  },
  "recipient": "John Doe",
  "city": "San Francisco",
  "country": "US"
}

get_wallet_balance

エージェントのウォレット残高を確認します。 出力:

{
  "address": "B5daxcMG9LgcXkZwuxBhHtuYxzG9J4ekgz1wUiMXw3xp",
  "balance": 2.5,
  "balanceLamports": 2500000000,
  "network": "devnet"
}

get_wallet_address

エージェントのウォレットアドレスを取得して資金を供給します。 出力:

{
  "address": "B5daxcMG9LgcXkZwuxBhHtuYxzG9J4ekgz1wUiMXw3xp",
  "network": "devnet",
  "message": "Send SOL to this address to fund your mail-sending operations"
}

会話の例

Claudeとの会話:

You: Send a thank you note to John Doe at 123 Main St, San Francisco, CA 94102

Claude: I'll help you send that thank you note via physical mail using Solana!

Let me first check the cost and then send the letter.

[Uses get_mail_quote tool]
The cost will be $1.50 (approximately 0.015 SOL) for domestic US mail.

[Uses send_mail tool]
✓ Letter sent successfully!

Your thank you note has been sent to John Doe and should arrive in 3-5 business days.

Transaction details:
- Letter ID: ltr_abc123
- Tracking: 9400000000000000000000
- Payment: 0.015 SOL (signature: 5j7s...)
- Expected delivery: February 7, 2026

You can view the letter preview at: https://...

仕組み

1. エージェントが手紙の内容を作成
2. MCPサーバーが受取人の住所を検証
3. Solanaトランザクションが作成され、エージェントのウォレットで署名
4. 支払いがSolMailマーチャントウォレットに送信
5. トランザクション署名がSolMail APIに送信
6. SolMailがオンチェーンの支払いを検証
7. 履行パートナー (Lob.com) が手紙を印刷
8. 手紙がUSPS/郵便サービスを通じて郵送
9. 追跡情報がエージェントに返される

アーキテクチャ

┌─────────────┐      MCP Protocol      ┌──────────────┐
│   Claude    │◄──────────────────────►│  SolMail MCP │
│  (AI Agent) │                        │    Server    │
└─────────────┘                        └──────┬───────┘
                                              │
                                              │ HTTPS API
                                              │
                    ┌─────────────────────────┼──────────────┐
                    │                         │              │
                    ▼                         ▼              ▼
              ┌──────────┐            ┌─────────────┐  ┌─────────┐
              │  Solana  │            │   SolMail   │  │   Lob   │
              │Blockchain│            │   Backend   │  │ Printing│
              │(Payment) │            │  (Verify)   │  │ & Mail  │
              └──────────┘            └─────────────┘  └─────────┘

価格

• 米国内の手紙: $1.50
• 国際手紙: $2.50
• カラー印刷: +$0.50
• Solanaトランザクション手数料: ~$0.00025

価格はUSDで表示され、CoinGecko APIを使用して現在の市場レートで自動的にSOLに変換されます。

開発

# 開発用のウォッチモード
npm run dev

# 本番用にビルド
npm run build

# サーバーを起動
npm start

セキュリティに関する考慮事項

1. 専用ウォレット: AIエージェント用に資金制限付きの別のウォレットを作成します
2. 秘密鍵のセキュリティ: SOLANA_PRIVATE_KEY を安全に保管し、gitにコミットしないでください
3. devnetでのテスト: メインネットを使用する前にdevnetで十分にテストします
4. レート制限: 自律エージェントの支出制限を実装します
5. 内容のレビュー: 本番環境では、郵便の内容を送信前にレビューすることを検討します

本番環境へのデプロイ

テストモードから本番モードへの切り替え

ハッカソンのデモではテストモード（実際の郵便は送られません）を使用しています。実際の郵便を送るには：

1. ライブのLob APIキーを取得
   • https://dashboard.lob.com でサインアップします
   • 本人確認を完了します
   • ライブのAPIキー（live_ で始まる）を取得します
2. 設定を更新 テストモード（現在）:

   SOLMAIL_API_URL=https://solmail.online/api
   SOLANA_NETWORK=devnet
   LOB_API_KEY=test_...
   

   本番モード:

   SOLMAIL_API_URL=https://solmail.online/api
   SOLANA_NETWORK=mainnet-beta
   SOLANA_RPC_URL=https://api.mainnet-beta.solana.com
   LOB_API_KEY=live_YOUR_KEY_HERE
   

3. 本番用のウォレットに実際のSOLを供給
   • メインネットのウォレットを作成: solana-keygen new --outfile mainnet-wallet.json
   • ウォレットアドレスにSOLを送信
   • コスト: 手紙1通あたり約0.011 SOL（$138/SOLの場合、約$1.50）
4. テストとデプロイ

   # 本番環境の設定でローカルでテスト
   npm run dev
   
   # 本番環境にデプロイ
   vercel --prod
   

   ⚠️ 重要: 本番モードでは実際の郵便が送られ、実際のSOLが請求されます。まずdevnetで十分にテストしてください！

ハイブリッドテスト（推奨）

実際のSOLを使わずに実際の郵便配達をテストするには：

LOB_API_KEY=live_YOUR_KEY  # 実際の郵便
SOLANA_NETWORK=devnet       # 無料のSOL

これにより、メインネットに切り替える前に郵便配達が正常に機能することを確認できます！

制限事項

• 現在は平文の手紙のみサポート（PDFサポートは近日追加予定）
• SOL残高のあるウォレットが必要
• 郵便の配達には時間がかかります（即時ではありません）
• 郵便の内容は履行パートナー (Lob.com) によってポリシー遵守のためにレビューされます
• 本番モードではLobアカウントの確認が必要（1 - 2営業日）

ロードマップ

• [ ] PDF添付のサポート
• [ ] 複数の手紙テンプレート
• [ ] はがきのサポート
• [ ] パッケージ/商品の配送
• [ ] 返信先住所の管理
• [ ] 一括送信の最適化
• [ ] USDC支払いのサポート
• [ ] マルチチェーンのサポート（EVMチェーン）

サポートとリンク

• Webサイト: https://solmail.online
• APIドキュメント: https://solmail.online/docs
• Solanaドキュメント: https://docs.solana.com
• MCPドキュメント: https://modelcontextprotocol.io

📄 ライセンス

MIT

クレジット

以下の技術を使用して構築されています:

• Model Context Protocol by Anthropic
• Solana ブロックチェーン
• Lob.com 印刷と郵送API

コロシアムエージェントハッカソン 🏛️ 向けに作成

AIエージェントと物理世界を1通の手紙ずつつなぎます。