Scan to contactarticle
README
🚀 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://...
工作原理
- 代理撰写信件内容
- MCP 服务器验证收件人地址
- Solana 交易由代理钱包创建并签名
- 支付款项发送到 SolMail 商户钱包
- 交易签名提交到 SolMail API
- SolMail 验证链上支付
- 信件由履行合作伙伴（Lob.com）打印
- 信件通过美国邮政服务/邮政服务邮寄
- 跟踪信息返回给代理
架构
┌─────────────┐ 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
安全注意事项
- 专用钱包：为你的 AI 代理创建一个资金有限的独立钱包
- 私钥安全：安全存储
SOLANA_PRIVATE_KEY，切勿提交到 git - Devnet 测试：在使用主网之前，在 devnet 上进行充分测试
- 速率限制：为自主代理实施消费限制
- 内容审核：（在生产环境中）考虑在发送邮件之前审核邮件内容
生产部署
从测试模式切换到生产模式
黑客松演示使用的是测试模式（不发送真实邮件）。要发送真实邮件：
- 获取实时 Lob API 密钥
- 在 https://dashboard.lob.com 注册
- 完成身份验证
- 获取你的实时 API 密钥（以
live_开头）
- 更新配置 测试模式（当前）：
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
- 用真实的 SOL 为钱包充值
- 创建主网钱包：
solana-keygen new --outfile mainnet-wallet.json - 将 SOL 发送到钱包地址
- 费用：每封信约 0.011 SOL（按 138 美元/SOL 计算，约 1.50 美元）
- 创建主网钱包：
- 测试并部署
# 使用生产配置在本地进行测试
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
鸣谢
使用以下技术构建：
为斗兽场代理黑客松而打造 🏛️
一次一封信，架起 AI 代理与现实世界的桥梁。