:mailbox_with_mail: solmail-mcp

![npm version](https://www.npmjs.com/package/solmail-mcp) ![License: MIT](https://opensource.org/licenses/MIT) ![GitHub stars](https://github.com/ExpertVagabond/solmail-mcp/stargazers) ![Solana](https://solana.com)

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

npx solmail-mcp@latest

Add to your MCP config:

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

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

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

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