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 代理与现实世界的桥梁。