faucet-mcp

MCP server that lets a coding agent request small dev funds (ETH/WETH/USDC/USDT) from a personal hot wallet, with caps and TOTP approval so a misbehaving agent can't drain it.

Why

Agent work on smart wallets constantly needs small dev top-ups: fund a fresh smart account, seed a session key, test on a new chain. Public faucets are unreliable and rate-limited; topping up by hand is friction. This is a self-hosted faucet over MCP behind tight per-call and 24h budgets.

Features

• Two MCP tools: send (transfer) and status (balances + remaining budget).

• Two-layer caps scoped per (chain class, token pool):

  • Soft caps — enforced unconditionally.

  • Hard caps (10× soft) — also unconditional and not bypassable with a code.

• TOTP approval required for amounts above the soft cap; codes are single-use within a 90s replay window.

• Token pools: USDC + USDT share a STABLE window; ETH + WETH share ETHWETH.

• JIT WETH wrap on native-ETH chains — sends WETH even when the funder only holds ETH.

• Rolling 24h windows, pruned on each read.

• Chains: ethereum, base, arbitrum, optimism, polygon, plasma + their sepolia testnets and plasma-testnet.

Caps (defaults)

Setup

bun install
bun run setup            # generates a FAUCET_TOTP_SECRET + otpauth URI
cp .env.example .env     # then fill FUNDING_PRIVATE_KEY and FAUCET_TOTP_SECRET

Add the printed otpauth:// URI (or scan the QR) into Apple Passwords / 1Password as a verification-code entry. Fund the hot wallet with small dev amounts on the chains/tokens you expect to use.

Smoke-test the TOTP loop:

bun run bin/verify.ts <6-digit code from your authenticator>

Configuration

Wire into Claude Code

~/.claude.json or project .claude/settings.json:

{
  "mcpServers": {
    "faucet": {
      "command": "bun",
      "args": ["run", "--cwd", "/absolute/path/to/faucet-mcp", "src/server.ts"]
    }
  }
}

bun run --cwd <dir> makes Bun auto-load .env from the faucet directory, so the MCP can be invoked from any cwd.

Tools

• send(amount, token, chain, recipient, code?) — execute a transfer. amount is a decimal string in human units (e.g. "0.5"), never wei. code is required only when the request exceeds the soft cap.

• status(chain?, token?) — funder balances, configured caps, used budget, remaining window. Use this to plan before calling send.

License

MIT — see LICENSE.

For the full design notes, threat model, and limitations: see AGENTS.md.