📦

io.github.ExpertVagabond/solmail

Name: io.github.ExpertVagabond/solmail
Rating: 1.9

Send physical mail with Solana cryptocurrency - AI agents can send real letters worldwide

0 installs

Trust: 37 — Low

Devtools

Ask AI about io.github.ExpertVagabond/solmail

I know everything about io.github.ExpertVagabond/solmail. Ask me about installation, configuration, usage, or troubleshooting.

0/500

Loading tools...

Reviews

Documentation

SolMail MCP Server

Send real physical mail using Solana cryptocurrency from your AI agent.

SolMail MCP is a Model Context Protocol (MCP) server that enables AI agents like Claude to send physical letters and postcards to real addresses worldwide, paid for with Solana (SOL) cryptocurrency. Perfect for agents that need to interact with the physical world.

🏆 Built for Colosseum Agent Hackathon ✅ Production-Ready - Switch from test mode to production with simple config changes 🧪 Demo Mode - Test with devnet SOL and Lob test API (no real charges) 🚀 Production Mode - Real mail delivery with mainnet SOL

Features

📬 Send Real Mail: Physical letters printed and mailed to any address
💰 Crypto Payments: Pay with SOL on Solana (devnet or mainnet)
🌍 Worldwide Delivery: Send to 200+ countries
🤖 AI-Native: Built specifically for AI agent integration
⚡ Fast & Cheap: Solana's sub-second finality and ~$0.00025 transaction fees
🔒 Non-Custodial: Direct wallet control, no intermediaries

Use Cases

Autonomous Customer Service: AI agents sending thank-you notes or receipts
AI-Driven Marketing: Personalized postcards generated and sent by AI
Smart Contracts: Trigger physical mail based on on-chain events
AI Personal Assistant: "Claude, send a birthday card to my mom"
Automated Reminders: Physical notifications for important events

Installation

# Clone or create the project
git clone <repository-url>
cd solmail-mcp

# Install dependencies
npm install

# Build the TypeScript code
npm run build

Configuration

Create a .env file based on .env.example:

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

# Solana Wallet (your agent's wallet private key)
# IMPORTANT: Use a dedicated wallet with limited funds for AI agents
SOLANA_PRIVATE_KEY=your_base58_private_key_here

# Solana Network
SOLANA_NETWORK=devnet
# Options: devnet (for testing), mainnet-beta (for production)

# Optional: Merchant wallet (where payments go)
# If not set, uses SolMail's default merchant wallet
MERCHANT_WALLET=<merchant_solana_address>

Getting a Solana Wallet

To use this MCP server, your AI agent needs its own Solana wallet:

# Install Solana CLI (if not already installed)
sh -c "$(curl -sSfL https://release.solana.com/stable/install)"

# Generate a new keypair
solana-keygen new --outfile ~/.config/solana/agent-wallet.json

# Get the private key in base58 format
solana-keygen pubkey ~/.config/solana/agent-wallet.json  # This is your public address

# To get the private key as base58 (for .env file):
# The keypair JSON file contains the private key bytes

Important: For AI agents, create a dedicated wallet and only fund it with the amount needed for mail sending. Never use your primary wallet.

Funding Your Wallet

For Devnet (Testing):

# Airdrop free devnet SOL
solana airdrop 2 <your-wallet-address> --url devnet

For Mainnet (Production): Transfer SOL to your agent's wallet address. Each letter costs approximately:

Domestic (US): $1.50 = ~0.015 SOL (at $100/SOL)
International: $2.50 = ~0.025 SOL (at $100/SOL)
Plus Solana transaction fee: ~$0.00025

Usage with Claude Desktop

Add to your Claude Desktop MCP settings file:

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"
      }
    }
  }
}

Restart Claude Desktop after adding the configuration.

Available Tools

`get_mail_quote`

Get a price quote for sending mail.

Input:

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

Output:

{
  "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`

Send physical mail with Solana payment.

Input:

{
  "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"
  }
}

Output:

{
  "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`

Check your agent's wallet balance.

Output:

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

`get_wallet_address`

Get your agent's wallet address for funding.

Output:

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

Example Conversations

With 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://...

How It Works

Agent composes letter content
MCP server validates recipient address
Solana transaction is created and signed by agent's wallet
Payment is sent to SolMail merchant wallet
Transaction signature is submitted to SolMail API
SolMail verifies the on-chain payment
Letter is printed by fulfillment partner (Lob.com)
Letter is mailed via USPS/postal service
Tracking info returned to agent

Architecture

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

Pricing

US Domestic Letter: $1.50
International Letter: $2.50
Color Printing: +$0.50
Solana Transaction Fee: ~$0.00025

Prices are in USD and automatically converted to SOL at current market rates using CoinGecko API.

Development

# Watch mode for development
npm run dev

# Build for production
npm run build

# Run the server
npm start

Security Considerations

Dedicated Wallet: Create a separate wallet for your AI agent with limited funds
Private Key Security: Store SOLANA_PRIVATE_KEY securely, never commit to git
Devnet Testing: Test thoroughly on devnet before using mainnet
Rate Limiting: Implement spending limits for autonomous agents
Content Review: Consider reviewing mail content before sending (for production)

Production Deployment

Switching from Test to Production

The hackathon demo uses test mode (no real mail sent). To send real mail:

1. Get Live Lob API Key

Sign up at https://dashboard.lob.com
Complete identity verification
Get your live API key (starts with live_)

2. Update Configuration

Test Mode (Current):

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

Production Mode:

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. Fund Wallet with Real SOL

Create mainnet wallet: solana-keygen new --outfile mainnet-wallet.json
Send SOL to wallet address
Cost: ~~0.011 SOL per letter (~~$1.50 at $138/SOL)

4. Test & Deploy

# Test locally with production config
npm run dev

# Deploy to production
vercel --prod

⚠️ Important: Production mode sends real mail and charges real SOL. Test thoroughly on devnet first!

Hybrid Testing (Recommended)

Test real mail delivery without spending real SOL:

LOB_API_KEY=live_YOUR_KEY  # Real mail
SOLANA_NETWORK=devnet       # Free SOL

This verifies mail delivery works before switching to mainnet!

Limitations

Currently supports plain text letters only (PDF support coming soon)
Requires wallet with SOL balance
Subject to postal delivery times (not instant)
Mail content reviewed by fulfillment partner (Lob.com) for policy compliance
Production mode requires Lob account verification (1-2 business days)

Roadmap

Support & Links

Website: https://solmail.online
API Docs: https://solmail.online/docs
Solana Docs: https://docs.solana.com
MCP Docs: https://modelcontextprotocol.io

License

MIT

Credits

Built with:

Model Context Protocol by Anthropic
Solana blockchain
Lob.com print & mail API

Made for the Colosseum Agent Hackathon 🏛️

Bridging AI agents and the physical world, one letter at a time.

io.github.ExpertVagabond/solmail

Reviews

Documentation

SolMail MCP Server

Features

Use Cases

Installation

Configuration

Getting a Solana Wallet

Funding Your Wallet

Usage with Claude Desktop

Available Tools

get_mail_quote

send_mail

get_wallet_balance

get_wallet_address

Example Conversations

How It Works

Architecture

Pricing

Development

Security Considerations

Production Deployment

Switching from Test to Production

1. Get Live Lob API Key

2. Update Configuration

3. Fund Wallet with Real SOL

4. Test & Deploy

Hybrid Testing (Recommended)

Limitations

Roadmap

Support & Links

License

Credits

Security Checklist

`get_mail_quote`

`send_mail`

`get_wallet_balance`

`get_wallet_address`