Invoice Parser MCP

Parse invoices, receipts, and financial documents into structured JSON — from your AI agent.

Built for the Model Context Protocol. Powered by Claude Vision.

What it does

Extracts structured data from PDF invoices, scanned receipts, and image files. No templates, no OCR configuration — Claude Vision reads the document and returns clean JSON.

Tools

Tool Reference

parse_invoice

Full invoice parsing. Extracts every structured field from a vendor invoice.

Parameters

*Either api_key or payment_proof must be provided.

Example input

{
  "file_path": "/Users/me/documents/invoice_acme_jan2025.pdf",
  "api_key": "ip_free_abc123"
}

Example output

{
  "ok": true,
  "document_type": "invoice",
  "vendor": {
    "name": "Acme Corp",
    "address": "123 Industrial Way, Austin TX 78701",
    "email": "[email protected]",
    "phone": "512-555-0100",
    "tax_id": "12-3456789"
  },
  "bill_to": {
    "name": "Jane Smith",
    "address": "456 Oak Ave, Boston MA 02101",
    "email": "[email protected]"
  },
  "invoice_number": "INV-2025-0142",
  "invoice_date": "2025-01-15",
  "due_date": "2025-02-15",
  "payment_terms": "Net 30",
  "currency": "USD",
  "line_items": [
    {
      "description": "Software consulting — January",
      "quantity": 40,
      "unit_price": 175.0,
      "total": 7000.0,
      "tax_rate": 0.0
    }
  ],
  "subtotal": 7000.0,
  "discount": 0.0,
  "tax_amount": 560.0,
  "shipping": 0.0,
  "total": 7560.0,
  "amount_due": 7560.0,
  "notes": "Wire transfer preferred. See banking details on page 2.",
  "po_number": "PO-98765"
}

parse_receipt

Parse a retail or expense receipt. Designed for point-of-sale receipts, restaurant bills, and expense claim documents.

Parameters

Example input

{
  "file_path": "/Users/me/receipts/coffee_shop_march1.jpg",
  "api_key": "ip_free_abc123"
}

Example output

{
  "ok": true,
  "document_type": "receipt",
  "merchant": {
    "name": "Blue Bottle Coffee",
    "address": "300 Webster St, Oakland CA 94609",
    "phone": "510-555-0200",
    "website": "bluebottlecoffee.com"
  },
  "date": "2025-03-01",
  "time": "09:14",
  "receipt_number": "5541",
  "cashier": "Maria",
  "items": [
    { "name": "Latte (large)", "quantity": 1, "unit_price": 6.50, "total": 6.50, "sku": "", "category": "beverage" },
    { "name": "Croissant", "quantity": 1, "unit_price": 4.00, "total": 4.00, "sku": "", "category": "pastry" }
  ],
  "subtotal": 10.50,
  "discounts": 0.0,
  "tax": 0.84,
  "tip": 2.00,
  "total": 13.34,
  "currency": "USD",
  "payment_method": "Visa",
  "card_last_four": "4242",
  "transaction_id": "TXN-88821",
  "loyalty_points": null,
  "notes": ""
}

extract_line_items

Lightweight extraction that returns only the itemized list. Faster and cheaper than parse_invoice when you only need the line items.

Parameters

Example output

{
  "ok": true,
  "line_items": [
    { "description": "Widget A (x10)", "quantity": 10, "unit_price": 12.00, "total": 120.00 },
    { "description": "Widget B (x5)",  "quantity": 5,  "unit_price": 24.00, "total": 120.00 }
  ],
  "item_count": 2
}

extract_totals

Extract only the financial summary (subtotal, taxes, totals, due date) without parsing line items or vendor details.

Parameters

Example output

{
  "ok": true,
  "currency": "USD",
  "subtotal": 240.00,
  "discount": 0.0,
  "tax_amount": 19.20,
  "tax_rate": 8.0,
  "shipping": 0.0,
  "tip": 0.0,
  "total": 259.20,
  "amount_due": 259.20,
  "invoice_date": "2025-01-15",
  "due_date": "2025-02-15"
}

validate_invoice

Math validation tool. Verifies that line item totals equal quantity × unit_price, that the subtotal matches the sum of line items, that the tax calculation is consistent, and that the final total reconciles. Allows ±$0.02 rounding tolerance.

Parameters

Example output — valid invoice

{
  "ok": true,
  "valid": true,
  "issues": [],
  "summary": {
    "line_items_checked": 3,
    "subtotal": 450.00,
    "tax": 36.00,
    "total": 486.00,
    "currency": "USD"
  }
}

Example output — invalid invoice

{
  "ok": true,
  "valid": false,
  "issues": [
    {
      "field": "line_item_2_total",
      "expected": 120.00,
      "found": 100.00,
      "description": "quantity (10) × unit_price (12.00) = 120.00, but stated total is 100.00"
    }
  ],
  "summary": {
    "line_items_checked": 3,
    "subtotal": 340.00,
    "tax": 27.20,
    "total": 367.20,
    "currency": "USD"
  }
}

export_to_csv

Batch parse up to 20 invoices or receipts and export a summary CSV. Each row contains: filename, document type, vendor/merchant, date, number, subtotal, tax, total, currency, due date, payment method.

Parameters

Example input

{
  "file_paths": [
    "/Users/me/invoices/jan2025.pdf",
    "/Users/me/invoices/feb2025.pdf",
    "/Users/me/receipts/expense_march.jpg"
  ],
  "output_path": "/Users/me/exports/q1_summary.csv",
  "api_key": "ip_free_abc123"
}

Example output (JSON response)

{
  "ok": true,
  "output_path": "/Users/me/exports/q1_summary.csv",
  "rows_written": 3,
  "errors": []
}

CSV columns: filename, document_type, vendor_merchant, date, number, subtotal, tax, total, currency, due_date, payment_method

Supported formats

• PDF (invoices, scanned documents)
• PNG, JPG, WEBP (photos of receipts, screenshots)

Authentication

Free tier: 20 parses/month with an API key (get one at plenitudo.ai)

Pay-per-use (x402): No account needed. Send USDC on Base to the wallet address, pass the tx hash as payment_proof.

{
  "error": "Payment required",
  "x402": {
    "network": "base",
    "token": "USDC",
    "recipient": "0x9053FeDC90c1BCB4a8Cf708DdB426aB02430d6ad",
    "amount_usdc": 0.05
  }
}

Usage (Claude Desktop / MCP client)

{
  "mcpServers": {
    "invoice-parser": {
      "url": "https://invoice-parser.plenitudo.ai/mcp"
    }
  }
}

Architecture

server.py          — MCP server (6 tools: parse_invoice, parse_receipt,
                     extract_line_items, extract_totals, validate_invoice,
                     export_to_csv)
auth.py            — API key validation + usage tracking (SQLite)
x402.py            — x402 micropayment verification (USDC on Base)
config.py          — Environment variable loading
worker.js          — Cloudflare Worker (remote proxy for MCP traffic)
data/keys.db       — API key store (created at runtime)
data/usage.db      — Monthly usage counters (created at runtime)
logs/              — Structured log files
tests/             — Unit tests (mock Vision API, no real documents needed)

Request flow

AI agent (Claude Desktop, Cursor, etc.)
    │
    │  MCP tool call (JSON-RPC over HTTP)
    ▼
Cloudflare Worker (worker.js)        ← optional remote proxy
    │
    │  Forwards to Railway deployment
    ▼
server.py (FastMCP, streamable HTTP)
    │
    ├── auth.py              validates API key / x402 proof
    ├── x402.py              verifies USDC transaction on Base
    └── Anthropic API        Claude Vision reads the document
            │
            ▼
        structured JSON → returned to agent

Environment variables

Deployment (Railway)

1. Fork this repo
2. Connect to Railway → New Project → Deploy from GitHub
3. Add environment variables:
   • ANTHROPIC_API_KEY — your Anthropic API key
   • INVOICEPARSER_DATA_DIR — /data
   • STRIPE_WEBHOOK_SECRET — from Stripe dashboard
   • STRIPE_PRO_PRICE_ID — from Stripe dashboard
4. Add a persistent volume at /data
5. Deploy

Running locally (optional maxproxy routing)

If you run the server on the same machine as a maxproxy instance on port 3456, you can route Claude Vision calls through it instead of hitting the Anthropic API directly:

ANTHROPIC_API_KEY=maxproxy
ANTHROPIC_BASE_URL=http://localhost:3456

Leave ANTHROPIC_BASE_URL unset (or empty) in any cloud/Railway deployment — those environments cannot reach a local proxy.

Contributing & Security

• CONTRIBUTING.md — dev setup and PR guidelines
• SECURITY.md — responsible disclosure policy
• CHANGELOG.md — version history

License

MIT — Copyright © 2025 Kenneth Nygren / Plenitudo AI