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

Copy the example environment file:

cp .env.example .env

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.

| Parameter | Required | Description | |-----------|----------|-------------| | address | No | Address to check. Defaults to your wallet. |

Example prompt: `` Check my USDC balance ``

---

`pay_send`

Send USDC to an address.

| Parameter | Required | Description | |-----------|----------|-------------| | to | Yes | Recipient address (0x...) | | amount | Yes | Amount in USDC (e.g., "10.50") | | memo | No | Note for this payment |

Example prompt: `` Send 25 USDC to 0x742d35Cc6634C0532925a3b844Bc9e7595f8d123 for "Coffee subscription" ``

---

`pay_request`

Generate a payment request link.

| Parameter | Required | Description | |-----------|----------|-------------| | amount | Yes | Amount to request in USDC | | memo | No | Description for the request |

Example prompt: `` Create a payment request for 50 USDC for "Consulting services" ``

---

`pay_history`

View recent USDC transactions.

| Parameter | Required | Description | |-----------|----------|-------------| | limit | No | Number of transactions (default: 20, max: 100) |

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)

| Setting | Value | |---------|-------| | Chain | Base (Chain ID: 8453) | | USDC Contract | 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913 | | Explorer | https://basescan.org |

Testnet

Set NETWORK=testnet in your .env:

| Setting | Value | |---------|-------| | Chain | Base Sepolia (Chain ID: 84532) | | USDC Contract | 0x036CbD53842c5426634e7929541eC2318f3dCF7e | | Explorer | https://sepolia.basescan.org |

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

---

⚙️ Environment Variables

| Variable | Required | Default | Description | |----------|----------|---------|-------------| | PRIVATE_KEY | ✅ Yes | - | Wallet private key (without 0x prefix) | | NETWORK | No | mainnet | mainnet or testnet | | BASE_RPC_URL | No | Public RPC | Custom RPC endpoint | | GAS_MULTIPLIER | No | 1.1 | Gas estimate multiplier | | MAX_GAS_LIMIT | No | 100000 | Maximum gas limit |

---

🔒 Security Considerations

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

Transaction Safety:

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

Network Selection:

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

---

🔧 Tech Stack

| Component | Technology | |-----------|------------| | Runtime | Node.js 18+ | | Language | TypeScript 5.7 | | MCP SDK | @modelcontextprotocol/sdk | | Blockchain | viem | | Validation | zod |

---

🤝 Contributing

Contributions are welcome! Please:

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Make your changes
Run tests (npm test)
Commit your changes (git commit -m 'Add amazing feature')
Push to the branch (git push origin feature/amazing-feature)
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

---

⚠️ Disclaimer: This is experimental software. Use at your own risk. Always verify transactions and test on testnet before using with real funds.

pay-mcp