Pay-MCP 💸

MCP server for USDC payments on Base — Enable any Claude Code agent to send and receive payments.

🎯 Overview

Pay-MCP is a Model Context Protocol (MCP) server that wraps USDC payment capabilities on the Base blockchain. It allows AI agents (like Claude Code) to:

• 💰 Check USDC balances — Query any wallet's USDC balance
• 📤 Send USDC payments — Transfer USDC to any address
• 📥 Generate payment requests — Create payment links with deep linking support
• 📜 View transaction history — List recent sent/received transfers

🏗️ Architecture

┌─────────────────────────────────────────────────────────────────┐
│                         Your Computer                           │
│  ┌─────────────────┐     stdio      ┌──────────────────────┐   │
│  │   Claude Code   │◄──────────────►│      Pay-MCP         │   │
│  │  (MCP Client)   │   JSON-RPC     │    (MCP Server)      │   │
│  └─────────────────┘                │                      │   │
│                                     │  ┌────────────────┐  │   │
│                                     │  │  PayWallet     │  │   │
│                                     │  │  ├─ viem       │  │   │
│                                     │  │  └─ ERC-20 ABI │  │   │
│                                     │  └────────────────┘  │   │
│                                     └──────────┬───────────┘   │
└────────────────────────────────────────────────┼───────────────┘
                                                 │ HTTPS/RPC
                                                 ▼
                                     ┌──────────────────────┐
                                     │    Base Blockchain   │
                                     │  ┌────────────────┐  │
                                     │  │  USDC Contract │  │
                                     │  │  (Circle)      │  │
                                     │  └────────────────┘  │
                                     └──────────────────────┘

🚀 Quick Start

Installation

# Clone the repository
git clone https://github.com/koriyoshi2041/pay-mcp.git
cd pay-mcp

# Install dependencies
npm install

# Build
npm run build

Configuration

1. Copy the example environment file:

cp .env.example .env

1. Edit .env with your private key:

# Required: Your wallet's private key
PRIVATE_KEY=your_private_key_here

# Optional: Network (mainnet or testnet)
NETWORK=mainnet

⚠️ Security Warning: Never commit your .env file or share your private key!

Add to Claude Code

Add this to your Claude Code MCP settings:

Location: ~/.claude/claude_desktop_config.json (macOS/Linux) or via Claude Code settings

{
  "mcpServers": {
    "pay-mcp": {
      "command": "node",
      "args": ["/path/to/pay-mcp/dist/index.js"],
      "env": {
        "PRIVATE_KEY": "your_private_key_here",
        "NETWORK": "mainnet"
      }
    }
  }
}

Alternative: Run directly with source:

{
  "mcpServers": {
    "pay-mcp": {
      "command": "npx",
      "args": ["tsx", "/path/to/pay-mcp/src/index.ts"],
      "env": {
        "PRIVATE_KEY": "your_private_key_here",
        "NETWORK": "mainnet"
      }
    }
  }
}

🛠️ Tools

pay_balance

Check USDC balance for your wallet or any address.

Example prompt:

Check my USDC balance

pay_send

Send USDC to an address.

Example prompt:

Send 25 USDC to 0x742d35Cc6634C0532925a3b844Bc9e7595f8d123 for "Coffee subscription"

pay_request

Generate a payment request link.

Example prompt:

Create a payment request for 50 USDC for "Consulting services"

pay_history

View recent USDC transactions.

Example prompt:

Show my last 10 USDC transactions

💻 Development

Project Structure

pay-mcp/
├── src/
│   ├── index.ts      # MCP server entry point
│   ├── config.ts     # Configuration and constants
│   ├── wallet.ts     # Blockchain interaction layer (viem)
│   └── tools.ts      # MCP tool definitions
├── test/
│   └── test.ts       # Test script
├── dist/             # Compiled output
├── .env.example      # Environment template
├── package.json
├── tsconfig.json
└── README.md

Commands

# Build TypeScript
npm run build

# Run in development mode
npm run dev

# Run tests (uses testnet)
npm test

# Clean build output
npm run clean

Running Tests

# Run with auto-generated test wallet
npm test

# Run with your own testnet wallet
PRIVATE_KEY=your_testnet_key npm test

🌐 Network Configuration

Mainnet (Default)

Testnet

Set NETWORK=testnet in your .env:

💡 To get testnet USDC, use the Base Sepolia Faucet.

⚙️ Environment Variables

🔒 Security Considerations

1. Private Key Storage:

   • Never commit your private key to version control
   • Consider using environment variables or a secrets manager
   • For production, use hardware wallets or key management services

2. Transaction Safety:

   • Always test on testnet first
   • Double-check recipient addresses
   • Consider implementing daily/per-transaction limits

3. Network Selection:

   • Verify network configuration before mainnet transactions
   • Use testnet for development and testing

🔧 Tech Stack

🤝 Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Make your changes
4. Run tests (npm test)
5. Commit your changes (git commit -m 'Add amazing feature')
6. Push to the branch (git push origin feature/amazing-feature)
7. Open a Pull Request

📄 License

MIT License - see LICENSE for details.

🙏 Acknowledgments

• Model Context Protocol by Anthropic
• Base by Coinbase
• Circle USDC
• Viem - TypeScript Ethereum library