🔐 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

🔨 Development Checklist

Morning (Setup - 1-2 hours)

• Project structure created

• Dependencies installed

• Get testnet tokens (ETH, SOL, Base)

• Create OWS wallet

• Update .env with addresses

• Build project

Afternoon (Core Features - 3-4 hours)

• Wallet Manager implemented

• Policy Engine implemented

• MCP Server implemented

• Test with real testnet addresses

• Verify policy enforcement works

• Test all 3 tools with Claude

Evening (Demo & Polish - 2-3 hours)

• Record 2-min demo video

• Create submission materials

• Deploy to GitHub

• Write clear documentation

• Submit to hackathon

🎥 Demo Video Outline

2-Minute Demo:

0:00 - Introduction

• "AI agents need wallets. But they also need guardrails."

0:20 - Show the problem

• "Without limits, an agent could drain your wallet"

0:40 - Show the solution

• Live demo of Claude checking balance

• Claude sending small transaction (approved)

• Claude trying to overspend (blocked)

1:30 - Show the tech

• Quick code walkthrough

• Policy engine enforcement

• Multi-chain support

1:50 - Call to action

• "Built on OWS. Local-first. Self-custody."

• GitHub link

🚀 Production Roadmap

If this wins/scales:

Phase 1: Polish MVP

• Add actual OWS integration

• Broadcast to real testnets

• Transaction history tracking

Phase 2: Enhanced Features

• Custom policy templates

• Multi-user support

• Audit logging dashboard

Phase 3: Monetization

• Free tier: Personal use

• Pro ($49/mo): Team policies

• Enterprise: White-label solution

🤝 Contributing

Built for the OpenWallet Standard Hackathon - April 3, 2026

📄 License

MIT

🔗 Links

• OpenWallet Standard: https://openwallet.sh/

• Hackathon: https://hackathon.openwallet.sh/

• MCP Docs: https://modelcontextprotocol.io/