solmail-mcp
Advanced tools
MCP server for sending physical mail with Solana cryptocurrency - AI agents can send real letters autonomously
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
# Clone or create the project
git clone <repository-url>
cd solmail-mcp
# Install dependencies
npm install
# Build the TypeScript code
npm run build
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>
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.
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:
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.
get_mail_quoteGet 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_mailSend 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_balanceCheck your agent's wallet balance.
Output:
{
"address": "B5daxcMG9LgcXkZwuxBhHtuYxzG9J4ekgz1wUiMXw3xp",
"balance": 2.5,
"balanceLamports": 2500000000,
"network": "devnet"
}
get_wallet_addressGet your agent's wallet address for funding.
Output:
{
"address": "B5daxcMG9LgcXkZwuxBhHtuYxzG9J4ekgz1wUiMXw3xp",
"network": "devnet",
"message": "Send SOL to this address to fund your mail-sending operations"
}
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://...
┌─────────────┐ MCP Protocol ┌──────────────┐
│ Claude │◄──────────────────────►│ SolMail MCP │
│ (AI Agent) │ │ Server │
└─────────────┘ └──────┬───────┘
│
│ HTTPS API
│
┌─────────────────────────┼──────────────┐
│ │ │
▼ ▼ ▼
┌──────────┐ ┌─────────────┐ ┌─────────┐
│ Solana │ │ SolMail │ │ Lob │
│Blockchain│ │ Backend │ │ Printing│
│(Payment) │ │ (Verify) │ │ & Mail │
└──────────┘ └─────────────┘ └─────────┘
Prices are in USD and automatically converted to SOL at current market rates using CoinGecko API.
# Watch mode for development
npm run dev
# Build for production
npm run build
# Run the server
npm start
SOLANA_PRIVATE_KEY securely, never commit to gitThe hackathon demo uses test mode (no real mail sent). To send real mail:
live_)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
solana-keygen new --outfile mainnet-wallet.json# 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!
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!
MIT
Built with:
Made for the Colosseum Agent Hackathon 🏛️
Bridging AI agents and the physical world, one letter at a time.
FAQs
MCP server for sending physical mail with Solana cryptocurrency - AI agents can send real letters autonomously
The npm package solmail-mcp receives a total of 32 weekly downloads. As such, solmail-mcp popularity was classified as not popular.
We found that solmail-mcp demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Company News
Open source maintainers are under more pressure than ever. We're raising our open source program from the Team plan to the Business plan, free.
Security News
The supply chain control that delays freshly published gems now covers lockfile generation and gem vendoring in Ruby projects.
Security News
During a UK cyber test, a Mythos 5 agent used sockpuppets, social engineering, and prompt injection to try to get a maintainer to merge malware.