# 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)](https://modelcontextprotocol.io) 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

```bash
# 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:**
```bash
cp .env.example .env
```

2. **Edit `.env` with your private key:**
```bash
# 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

```json
{
  "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:

```json
{
  "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

```bash
# 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

```bash
# 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](https://www.alchemy.com/faucets/base-sepolia).

---

## ⚙️ 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](LICENSE) for details.

---

## 🙏 Acknowledgments

- [Model Context Protocol](https://modelcontextprotocol.io) by Anthropic
- [Base](https://base.org) by Coinbase
- [Circle USDC](https://www.circle.com/en/usdc)
- [Viem](https://viem.sh) - 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>