English Français العربية

io.github.ExpertVagabond/solmail

Official registry Finance and payments

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

Source code Documentation

What can you do with io.github.ExpertVagabond/solmail?

  • 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

Install

Add this to your client's MCP configuration (Claude Desktop: claude_desktop_config.json; Cursor: .cursor/mcp.json; VS Code and others use the same "mcpServers" shape).

NPM package solmail-mcp
Claude Code 
claude mcp add solmail -e 'SOLANA_PRIVATE_KEY=<your solana_private_key>' -e 'SOLANA_NETWORK=<SOLANA_NETWORK>' -e 'SOLMAIL_API_URL=<SOLMAIL_API_URL>' -e 'MERCHANT_WALLET=<MERCHANT_WALLET>' -- npx -y solmail-mcp@1.0.2
JSON configuration (Claude Desktop, Cursor, VS Code) 
{
    "mcpServers": {
        "solmail": {
            "command": "npx",
            "args": [
                "-y",
                "solmail-mcp@1.0.2"
            ],
            "env": {
                "SOLANA_PRIVATE_KEY": "<your solana_private_key>",
                "SOLANA_NETWORK": "<SOLANA_NETWORK>",
                "SOLMAIL_API_URL": "<SOLMAIL_API_URL>",
                "MERCHANT_WALLET": "<MERCHANT_WALLET>"
            }
        }
    }
}

Environment variables

  • SOLANA_PRIVATE_KEY required secret Your agent's Solana wallet private key (base58 or JSON array format)
  • SOLANA_NETWORK Solana network: devnet for testing, mainnet-beta for production
  • SOLMAIL_API_URL SolMail API endpoint
  • MERCHANT_WALLET Merchant wallet address for payments

Documentation

From the project's README on GitHub, refreshed weekly. Links open on GitHub.

Contents
  1. :mailbox_with_mail: solmail-mcp
  2. Install
  3. Features
  4. Tools (4)
  5. Usage Example
  6. How It Works
  7. Pricing
  8. Configuration
  9. Development
  10. Related Projects
  11. Contributing
  12. Links
  13. License

: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

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)

ToolDescription
get_mail_quoteGet price quote for sending mail (country, color options)
send_mailSend a physical letter with Solana payment
get_wallet_balanceCheck agent wallet SOL balance
get_wallet_addressGet 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

TypePriceSOL (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

VariableRequiredDescription
SOLANA_PRIVATE_KEYYesAgent wallet private key (base58)
SOLANA_NETWORKNodevnet (default) or mainnet-beta
SOLMAIL_API_URLNoAPI endpoint (default: https://solmail.online/api)
MERCHANT_WALLETNoCustom 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

Contributing

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

License

MIT -- Purple Squirrel Media

Frequently asked questions

What is io.github.ExpertVagabond/solmail?

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

How do I install io.github.ExpertVagabond/solmail?

It runs on your machine. In Claude Code: claude mcp add solmail -e 'SOLANA_PRIVATE_KEY=<your solana_private_key>' -e 'SOLANA_NETWORK=<SOLANA_NETWORK>' -e 'SOLMAIL_API_URL=<SOLMAIL_API_URL>' -e 'MERCHANT_WALLET=<MERCHANT_WALLET>' -- npx -y solmail-mcp@1.0.2. For other clients, paste the JSON configuration from this page into their MCP settings.

Does io.github.ExpertVagabond/solmail need an API key?

Yes. It expects SOLANA_PRIVATE_KEY, which you set in its configuration.

Is io.github.ExpertVagabond/solmail open source?

Yes. Its code is on GitHub under the MIT license.

Who maintains io.github.ExpertVagabond/solmail?

It is published by ExpertVagabond. AI.tn lists it but does not maintain or endorse it.

From the official MCP Registry. Listing is not an endorsement: review a server's code and permissions before giving it access to your data.