:mailbox_with_mail: solmail-mcp

Send real physical mail using Solana cryptocurrency from your AI agent. A Model Context Protocol server that enables Claude and other AI agents to send physical letters and postcards to real addresses worldwide, paid with SOL. Built for the Colosseum Agent Hackathon (#47).

Install

Terminal

npx solmail-mcp@latest

Add to your MCP config:

config.json

{
  "mcpServers": {
    "solmail": {
      "command": "npx",
      "args": ["-y", "solmail-mcp"],
      "env": {
        "SOLANA_NETWORK": "devnet",
        "SOLANA_PRIVATE_KEY": "your_base58_private_key"
      }
    }
  }
}

Features

Physical Mail -- Letters printed and mailed to 200+ countries via Lob.com
Solana Payments -- Pay with SOL on devnet (testing) or mainnet (production)
Non-Custodial -- Direct wallet control, no intermediaries
AI-Native -- Built specifically for MCP agent integration
Demo Mode -- Test with devnet SOL and Lob test API at zero cost

Tools (4)

Tool	Description
`get_mail_quote`	Get price quote for sending mail (country, color options)
`send_mail`	Send a physical letter with Solana payment
`get_wallet_balance`	Check agent wallet SOL balance
`get_wallet_address`	Get wallet address for funding

Usage Example

Code

You: Send a thank you note to John Doe at 123 Main St, San Francisco, CA 94102

Claude: [calls get_mail_quote] Cost: $1.50 (~0.015 SOL) for domestic US mail
        [calls send_mail] Letter sent!
          Letter ID: ltr_abc123
          Tracking: 9400000000000000000000
          Payment: 0.015 SOL (tx: 5j7s...)
          Delivery: 3-5 business days

How It Works

Code

Agent composes letter --> MCP validates address --> Solana tx signed
    --> Payment sent to merchant --> SolMail verifies on-chain
    --> Lob.com prints letter --> USPS delivers --> Tracking returned

Pricing

Type	Price	SOL (at $100/SOL)
US Domestic	$1.50	~0.015 SOL
International	$2.50	~0.025 SOL
Color printing	+$0.50	+0.005 SOL
Solana tx fee	~$0.00025	~0.0000025 SOL

Configuration

Variable	Required	Description
`SOLANA_PRIVATE_KEY`	Yes	Agent wallet private key (base58)
`SOLANA_NETWORK`	No	`devnet` (default) or `mainnet-beta`
`SOLMAIL_API_URL`	No	API endpoint (default: `https://solmail.online/api`)
`MERCHANT_WALLET`	No	Custom payment destination

Important: Create a dedicated wallet with limited funds for AI agents. Never use your primary wallet.

Development

Terminal

npm install && npm run build
npm run dev    # Watch mode
npm start      # Production

Related Projects

solana-mcp-server-app -- Solana wallet + DeFi MCP
coldstar-colosseum -- Air-gapped Solana vault
ordinals-mcp -- Bitcoin Ordinals MCP server
cpanel-mcp -- cPanel hosting MCP server

Contributing

Fork the repository
Create your feature branch (git checkout -b feature/my-feature)
Commit your changes
Open a Pull Request

License

MIT -- Purple Squirrel Media

Solmail MCP README