ClawCard

Virtual card management from the command line.
Create, freeze, unfreeze, and close Privacy.com cards without leaving your terminal.

npm  ·  GitHub  ·  Docs  ·  Skill

---

Install

# Run directly — no install needed
npx clawcard

# Or install globally
npm install -g clawcard

# Add as Claude Code skill
npx skills add kknd0/clawcard

# Add MCP server to Claude Code
claude mcp add clawcard -- npx clawcard-mcp

---

Quick Start

# Authenticate (email + one-time code)
clawcard login -e you@email.com

# One-time purchase — card auto-exhausts after use
clawcard burner 25.50 -m "amazon.com"

# Recurring service — create, pay, freeze, repeat
clawcard create -n "Spotify" -l 16 -c subscriptions
clawcard done <card-id>       # freeze after payment
clawcard use <card-id>        # unfreeze next month

---

Why ClawCard?

Privacy.com lets you create virtual debit cards for online purchases. ClawCard wraps their internal API into a fast, scriptable CLI — no browser needed.

• One command to create a card, pay, and lock it down
• npx ready — run without installing
• MCP server included — use your cards from Claude Code or any MCP client
• Claude Code skill — install via skills.sh
• Node.js 18+ — uses native fetch, minimal dependencies

---

Card Types

Burner Cards

Single-use cards for one-time purchases. Amount rounds up to the next whole dollar.

clawcard burner 49.99 -m "newegg.com"

Burner Card Created
  Number:   4242 8310 •••• 7291
  CVC:      •••
  Merchant: newegg.com
  Limit:    $50.00
  Type:     single use
  Status:   active
  ID:       a1b2c3d4-...

Reusable Cards

For subscriptions and recurring payments. Set a monthly spending limit and optional merchant category.

clawcard create -n "Netflix" -l 23 -c entertainment

Reusable Card Created
  Name:     Netflix
  Category: entertainment
  Limit:    $23.00/monthly
  Status:   active
  ID:       a1b2c3d4-...

---

Commands

Command	Description
login [-e email]	Authenticate with Privacy.com
logout	Clear saved credentials
burner <amount> -m <merchant>	Create a single-use card
create -n <name> -l <limit> [-c <cat>]	Create a reusable card
use <id>	Unfreeze a card for payment
done <id> [--fail]	Freeze after payment (--fail zeroes limit)
list [--state active|frozen|closed] [--month YYYY-MM]	List cards
show <id>	Show full card details
update <id> [--name] [--limit] [--category]	Update a card
close <id>	Permanently close a card
categories	List merchant categories
transactions [options]	Show transaction history

---

Workflows

ONE-TIME PURCHASE
  burner 25.50 -m "amazon.com"  ──▶  active  ──▶  payment  ──▶  exhausted

UNUSED BURNER ── SAVE FOR LATER
  burner 50 -m "store.com"      ──▶  active  ──▶  done <id>  ──▶  frozen
                                                   use <id>   ──▶  active

RECURRING PAYMENT
  create -n "Spotify" -l 16     ──▶  active  ──▶  payment
                                     done <id>  ──▶  frozen
                                     use <id>   ──▶  active  ──▶  payment
                                     done <id>  ──▶  frozen  ──▶  ...

PAYMENT FAILED
  done <id> --fail              ──▶  frozen + limit zeroed

Card state machine:

    ┌─────────┐     done      ┌─────────┐
    │  OPEN   │──────────────▶│ PAUSED  │
    │ (active)│◀──────────────│ (frozen)│
    └────┬────┘     use       └─────────┘
         │
         │ close
         ▼
    ┌─────────┐
    │ CLOSED  │  (permanent, cannot be undone)
    └─────────┘

---

Transaction History

View your spending history across all cards or filter by card, date, status, or merchant.

# Recent transactions (default: 20)
clawcard transactions

# Filter by status
clawcard txns --status settled

# Filter by merchant
clawcard txns --merchant spaceship

# Last 7 days, specific card
clawcard txns --since 7d --card <card-id>

# Combine filters
clawcard txns --since 2025-01 --status settled --limit 10

  2025-07-17 00:10  SPACESHIP.COM* RAFHEY    -$2.90      settled    spaceship.com [44126155]
  2025-07-03 21:56  RESUMEGENIUS.COM         -$2.95      settled    [43740979]

  2 transaction(s)

Filter Options

Flag	Example	Description
--card <id>	--card 53125488	Filter by card ID
--since <date>	--since 7d / --since 2025-01	Date range
--limit <n>	--limit 10	Max results (default: 20)
--status <s>	--status settled	settled, authorized, voided
--merchant <name>	--merchant amazon	Substring match

---

MCP Server

ClawCard includes a Model Context Protocol server for AI-assisted card management.

Setup

# Register with Claude Code
claude mcp add clawcard -- npx clawcard-mcp

Available Tools

Tool	Description
login_status	Check authentication state
list_cards	List all cards (filter by state/month)
get_card	Get full card details including PAN
create_burner	Create a single-use card
create_card	Create a reusable card with monthly limit
update_card	Update name, limit, or category
freeze_card	Pause a card
unfreeze_card	Resume a paused card
close_card	Permanently close a card
list_categories	List merchant categories
list_transactions	Transaction history with filters

---

Project Structure

bin/
  cli.js               Entry point (#!/usr/bin/env node)
  mcp-server.js        MCP server (11 tools)
lib/
  api.js               Privacy.com API client (native fetch)
  cli.js               All commands + input helpers
  config.js            Token storage (~/.clawcard/config.json, 0600)
  format.js            Colors, categories, formatting helpers
skills/
  clawcard/SKILL.md    Claude Code skill (skills.sh)
test/
  cli.test.js          Unit tests (node:test)
  e2e.test.js          E2E tests (real API, skips if not logged in)
privacy-extension-api.md   Full API reference

Testing

# Unit tests — no account needed
npm test

# E2E tests — requires login, creates a real $1 card and closes it
clawcard login
npm run test:e2e

E2E tests skip gracefully if not logged in.

---

Currency Reference

Field	Format	Example
spendLimit	Dollars (integer)	66 = $66.00
spentTotal	Dollars (float)	2.95 = $2.95
Transaction amount	Cents (divide by 100)	295 = $2.95

---

Merchant Categories

automotive    cleaning      digital       dining
education     entertainment groceries     health
home          nonprofit     pets          professional
retail        sports        subscriptions travel

Use prefix matching: -c din matches dining, -c ent matches entertainment.

---

Security

• Credentials stored at ~/.clawcard/config.json with 0600 permissions
• Directory permissions set to 0700
• No tokens in environment variables, command history, or logs
• Auth uses Privacy.com's email + one-time-code flow

Requirements

• Node.js 18+
• Dependencies: commander, @modelcontextprotocol/sdk, zod

License

MIT