Solmail MCP

🚀 SolMail MCP 服務器

使用 Solana 加密貨幣，讓你的 AI 代理發送真實的實體郵件。

SolMail MCP 是一個模型上下文協議（MCP）服務器，它能讓像 Claude 這樣的 AI 代理使用 Solana（SOL）加密貨幣，向全球真實地址發送實體信件和明信片。這對於需要與現實世界交互的代理來說再合適不過了。

🏆 為鬥獸場代理黑客松而構建 ✅ 可用於生產環境 - 通過簡單的配置更改，即可從測試模式切換到生產模式 🧪 演示模式 - 使用 devnet SOL 和 Lob 測試 API 進行測試（無實際費用） 🚀 生產模式 - 使用主網 SOL 進行真實郵件投遞

✨ 主要特性

• 📬 發送真實郵件：將實體信件打印並郵寄到任何地址
• 💰 加密貨幣支付：使用 Solana 上的 SOL 進行支付（devnet 或主網）
• 🌍 全球投遞：可發送到 200 多個國家
• 🤖 原生支持 AI：專為 AI 代理集成而構建
• ⚡ 快速且低成本：Solana 的亞秒級終結性和約 0.00025 美元的交易費用
• 🔒 非託管模式：直接控制錢包，無中間方

📦 安裝指南

# 克隆或創建項目
git clone <repository-url>
cd solmail-mcp

# 安裝依賴
npm install

# 構建 TypeScript 代碼
npm run build

📚 詳細文檔

配置

基於 .env.example 創建一個 .env 文件：

# SolMail API 配置
SOLMAIL_API_URL=https://solmail.online/api

# Solana 錢包（你的代理錢包私鑰）
# 重要提示：為 AI 代理使用一個資金有限的專用錢包
SOLANA_PRIVATE_KEY=your_base58_private_key_here

# Solana 網絡
SOLANA_NETWORK=devnet
# 選項：devnet（用於測試），mainnet-beta（用於生產）

# 可選：商戶錢包（支付款項的接收地址）
# 如果未設置，將使用 SolMail 的默認商戶錢包
MERCHANT_WALLET=<merchant_solana_address>

獲取 Solana 錢包

要使用此 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  # 這是你的公鑰地址

# 要獲取 base58 格式的私鑰（用於 .env 文件）：
# 密鑰對 JSON 文件包含私鑰字節

重要提示：為 AI 代理創建一個專用錢包，並僅為其提供發送郵件所需的資金。切勿使用你的主錢包。

為錢包充值

對於 Devnet（測試）：

# 空投免費的 devnet SOL
solana airdrop 2 <your-wallet-address> --url devnet

對於主網（生產）： 將 SOL 轉移到你的代理錢包地址。每封信的大致費用如下：

• 國內（美國）：1.50 美元 = 約 0.015 SOL（按 100 美元/SOL 計算）
• 國際：2.50 美元 = 約 0.025 SOL（按 100 美元/SOL 計算）
• 加上 Solana 交易費用：約 0.00025 美元

與 Claude Desktop 一起使用

將以下內容添加到你的 Claude Desktop MCP 設置文件中： macOS：~/Library/Application Support/Claude/claude_desktop_config.json Windows：%APPDATA%\Claude\claude_desktop_config.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。

可用工具

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 個工作日"
}

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 的對話：

你：給住在舊金山主街 123 號，郵編 94102 的 John Doe 發送一封感謝信。

Claude：我將幫助你使用 Solana 通過實體郵件發送那封感謝信！

我先查詢一下費用，然後發送信件。

[使用 get_mail_quote 工具]
美國國內郵件的費用將是 1.50 美元（約 0.015 SOL）。

[使用 send_mail 工具]
✓ 信件發送成功！

你的感謝信已發送給 John Doe，預計 3 - 5 個工作日內到達。

交易詳情：
- 信件 ID：ltr_abc123
- 跟蹤編號：9400000000000000000000
- 支付：0.015 SOL（簽名：5j7s...）
- 預計送達日期：2026 年 2 月 7 日

你可以在以下鏈接查看信件預覽：https://...

工作原理

1. 代理撰寫信件內容
2. MCP 服務器驗證收件人地址
3. Solana 交易由代理錢包創建並簽名
4. 支付款項發送到 SolMail 商戶錢包
5. 交易簽名提交到 SolMail API
6. SolMail 驗證鏈上支付
7. 信件由履行合作伙伴（Lob.com）打印
8. 信件通過美國郵政服務/郵政服務郵寄
9. 跟蹤信息返回給代理

架構

┌─────────────┐      MCP 協議      ┌──────────────┐
│   Claude    │◄──────────────────────►│  SolMail MCP │
│  (AI 代理) │                        │    服務器    │
└─────────────┘                        └──────┬───────┘
                                              │
                                              │ HTTPS API
                                              │
                    ┌─────────────────────────┼──────────────┐
                    │                         │              │
                    ▼                         ▼              ▼
              ┌──────────┐            ┌─────────────┐  ┌─────────┐
              │  Solana  │            │   SolMail   │  │   Lob   │
              │區塊鏈    │            │   後端      │  │ 打印與郵寄│
              │(支付)    │            │  (驗證)     │  │ 服務    │
              └──────────┘            └─────────────┘  └─────────┘

定價

• 美國國內信件：1.50 美元
• 國際信件：2.50 美元
• 彩色打印：+0.50 美元
• Solana 交易費用：約 0.00025 美元

價格以美元為單位，並使用 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 發送到錢包地址
   • 費用：每封信約 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 鏈）

支持與鏈接

• 網站：https://solmail.online
• API 文檔：https://solmail.online/docs
• Solana 文檔：https://docs.solana.com
• MCP 文檔：https://modelcontextprotocol.io

📄 許可證

MIT

鳴謝

使用以下技術構建：

• 模型上下文協議，由 Anthropic 開發
• Solana 區塊鏈
• Lob.com 打印與郵寄 API

為鬥獸場代理黑客松而打造 🏛️

一次一封信，架起 AI 代理與現實世界的橋樑。