MCP 服务器

ows-mcp-wallet

Enables AI agents to check balances and send transactions across multiple blockchains with automatic spending limit protection and policy enforcement.

README

🔐 OWS MCP Wallet - Agent Treasury with Spending Limits

MCP server that exposes OpenWallet Standard to Claude with built-in policy engine and spending limits.

Hackathon Tracks: #05 (Agent Treasury) + #06 (MCP Wallet Server)

🎯 What It Does

Allows AI agents (like Claude) to:

✅ Check wallet balances across multiple chains
✅ Send transactions with policy enforcement
✅ Automatic spending limit protection
✅ Multi-chain support (Ethereum, Solana, Base)
✅ Session-scoped security

Demo: Agent can't overspend even if instructed to!

🚀 Quick Start (15 Minutes!)

New: Auto-generate test wallets! No need for MetaMask/Phantom.

# 1. Install dependencies
cd ~/ows-mcp-wallet
npm install

# 2. Generate test wallet (creates addresses + private keys)
npm run generate

# 3. Copy output to .env file
# (Script tells you exactly what to copy)

# 4. Get testnet tokens
# Visit faucets (links in output)

# 5. Test it works
npm test
npm run cli balance

# 6. Send real testnet transaction!
npm run cli send ethereum-sepolia 0x000... 0.01

📖 Full walkthrough: See QUICKSTART.md for detailed 15-min guide

📚 Documentation

QUICKSTART.md ⭐ - 15-minute setup guide (start here!)
SETUP-GUIDE.md - Detailed step-by-step setup
ENV-VARIABLES.md - Complete environment variable reference
MOBILE-PLAN.md - Mobile-friendly hackathon guide
GETTING-STARTED.md - Friday build schedule

🔧 New Commands

npm run generate    # Generate test wallet
npm run test        # Verify configuration
npm run cli balance # Check balances
npm run cli policy  # View spending limits
npm run cli send    # Send test transaction
npm run build       # Build for production
npm run dev         # Run in watch mode

🔧 Configure Claude Desktop

Add to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json on Mac):

{
  "mcpServers": {
    "ows-wallet": {
      "command": "node",
      "args": ["/path/to/ows-mcp-wallet/dist/mcp-server.js"],
      "env": {
        "ETH_ADDRESS": "0xYourAddress",
        "SOL_ADDRESS": "YourSolanaAddress"
      }
    }
  }
}

Restart Claude Desktop.

🎬 Demo Script

Test 1: Check Balance

You: "What's my wallet balance?"
Claude: *calls get_balance tool*
Response: Shows balances across all chains

Test 2: Send Transaction (Allowed)

You: "Send 0.01 ETH to 0x123... on Sepolia"
Claude: *calls send_transaction*
Response: ✅ Transaction approved and prepared

Test 3: Overspending (Blocked)

You: "Send 100 ETH to 0x456..."
Claude: *calls send_transaction*
Response: ❌ DENIED - Exceeds $50 per-transaction limit

Test 4: Check Policy

You: "What are my spending limits?"
Claude: *calls check_policy*
Response: Shows daily limit, spent amount, remaining allowance

📊 Policy Engine

Default limits (configurable):

Daily limit: $100 USD
Per-transaction limit: $50 USD
Allowed chains: Sepolia, Devnet, Base Sepolia
Optional: Address whitelist

🏗️ Architecture

Claude (AI Agent)
    ↓
MCP Protocol
    ↓
OWS MCP Server
    ↓
Policy Engine (checks limits)
    ↓
Wallet Manager (prepares transaction)
    ↓
OWS (signs & broadcasts)
    ↓
Blockchain

📁 Project Structure

ows-mcp-wallet/
├── mcp-server.ts          # MCP server implementation
├── wallet-manager.ts      # Multi-chain wallet interface
├── policy-engine.ts       # Spending limits & policy
├── package.json
├── tsconfig.json
├── .env.example
├── testnet-setup.md       # Testnet token guide
└── README.md