wallet-mcp

Multi Wallet Generator + Manager — MCP Server for AI Agents

A production-ready MCP (Model Context Protocol) server that gives Claude, OpenClaw, Hermes, and any MCP-compatible AI agent full control over EVM and Solana wallets — generate, fund, scan, manage, all via natural language.

Architecture

Full architecture docs → assets/architecture.md

Tools

Tool	Description
`generate_wallets`	Generate N wallets (Solana or EVM), save to local CSV
`send_native_multi`	Send SOL / ETH from one wallet to a labeled group
`sweep_wallets`	Collect all SOL / ETH from a group back to one destination
`export_wallets`	Export a wallet group to JSON or CSV file for backup
`import_wallets`	Import wallets from a JSON or CSV file into storage
`list_wallets`	List wallets with chain / label / tag filters
`get_balance_batch`	Fetch native balances for a wallet group
`scan_token_balances`	Scan SPL / ERC-20 token balances across a wallet group
`close_token_accounts`	Close empty SPL token accounts, reclaim rent SOL
`scan_token_accounts`	Scan SPL token accounts for one wallet (read-only)
`add_wallet`	Import a single wallet by private key (address auto-derived)
`tag_wallets`	Add a tag to all wallets in a label group
`group_summary`	Show wallet groups and counts per chain
`delete_group`	Permanently delete all wallets in a group

Quickstart

# Install with uv (recommended)
uv tool install git+https://github.com/genoshide/wallet-mcp.git

# Or install from local clone
git clone https://github.com/genoshide/wallet-mcp
cd wallet-mcp
uv sync

See INSTALLATION.md for full setup including Claude Desktop config.

Claude Desktop Integration

Add to your claude_desktop_config.json:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
Linux: ~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "wallet-mcp": {
      "command": "uv",
      "args": [
        "tool", "run", "--from",
        "git+https://github.com/genoshide/wallet-mcp.git",
        "wallet-mcp"
      ]
    }
  }
}

Or if installed locally:

{
  "mcpServers": {
    "wallet-mcp": {
      "command": "uv",
      "args": ["--directory", "/path/to/wallet-mcp", "run", "wallet-mcp"]
    }
  }
}

Example Conversations

"Generate 50 Solana wallets for my airdrop campaign"

→ generate_wallets(chain="solana", count=50, label="airdrop1")

"Send 0.01 SOL to all airdrop1 wallets with random delays"

→ send_native_multi(from_key="...", label="airdrop1", amount=0.01,
                    chain="solana", randomize=True, delay_min=2, delay_max=15)

"How much SOL do the airdrop1 wallets have in total?"

→ get_balance_batch(label="airdrop1", chain="solana")

"Close all empty token accounts on my main wallet and tell me how much SOL I reclaimed"

→ close_token_accounts(private_key="...")

"Show me all my wallet groups"

→ group_summary()

"Sweep all leftover SOL from airdrop1 back to my main wallet"

→ sweep_wallets(to_address="YourMainWallet...", chain="solana", label="airdrop1")

"Import wallets from backup file into my airdrop2 group"

→ import_wallets(path="/backups/airdrop1.json", label="airdrop2")

"Export all airdrop1 wallets to a JSON file"

→ export_wallets(label="airdrop1", format="json", path="/backups/airdrop1.json")

"Check USDC balances across all my EVM wallets"

→ scan_token_balances(chain="evm", label="eth_test", token="0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48")

See EXAMPLES.md for more.

Data Storage

Wallets are stored at ~/.wallet-mcp/wallets.csv:

address,private_key,chain,label,tags,created_at
So1ana...abc,5Kd3N...,solana,airdrop1,,2024-01-01T00:00:00Z
0xABCD...,0x1234...,evm,test,vip|batch1,2024-01-01T00:00:00Z

Override storage location:

export WALLET_DATA_DIR=/secure/encrypted/path

Keep your wallets.csv secure. It contains private keys.

chmod 600 ~/.wallet-mcp/wallets.csv

Environment Variables

Copy .env.example → .env:

SOLANA_RPC_URL=https://api.mainnet-beta.solana.com
EVM_RPC_URL=https://mainnet.infura.io/v3/xxx
WALLET_DATA_DIR=~/.wallet-mcp
LOG_LEVEL=INFO

Project Structure

wallet-mcp/
├── pyproject.toml
├── .env.example
├── README.md
├── INSTALLATION.md
├── EXAMPLES.md
└── src/
    └── wallet_mcp/
        ├── __init__.py
        ├── server.py          ← FastMCP server, all tool definitions
        └── core/
            ├── evm.py         ← EVM: generate, balance, send
            ├── solana.py      ← Solana: generate, balance, send, token accounts
            ├── generator.py   ← Multi-chain wallet generator
            ├── distributor.py ← Multi-send with retry + randomization
            ├── manager.py     ← list, balance batch, tag, group summary
            ├── storage.py     ← CSV load/save/filter
            └── utils.py       ← delays, retry, logging, helpers

License

MIT License — see LICENSE for details.

Disclaimer: This tool is for educational and research purposes only. It does not constitute financial advice. Always do your own research before making investment decisions.