Pay-MCP 💸

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

<p align="center"> <a href="LICENSE"><img src="https://img.shields.io/badge/License-MIT-blue.svg" alt="License: MIT"></a> <a href="https://nodejs.org"><img src="https://img.shields.io/badge/Node.js-18+-339933?logo=node.js&logoColor=white" alt="Node.js 18+"></a> <a href="https://www.typescriptlang.org/"><img src="https://img.shields.io/badge/TypeScript-5.7-3178C6?logo=typescript&logoColor=white" alt="TypeScript"></a> <a href="https://base.org"><img src="https://img.shields.io/badge/Chain-Base-0052FF?logo=coinbase&logoColor=white" alt="Base"></a> <a href="https://www.circle.com/en/usdc"><img src="https://img.shields.io/badge/Token-USDC-2775CA?logo=circle&logoColor=white" alt="USDC"></a> <a href="https://modelcontextprotocol.io"><img src="https://img.shields.io/badge/Protocol-MCP-FF6B35" alt="MCP"></a> <a href="https://viem.sh"><img src="https://img.shields.io/badge/Blockchain-Viem-1C1C1C" alt="Viem"></a> </p>

---

🎯 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

2. 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

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

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

---

🤝 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

---

<p align="center"> <strong>⚠️ Disclaimer:</strong> This is experimental software. Use at your own risk. Always verify transactions and test on testnet before using with real funds. </p>