Invoice Parser

БесплатноHosted

Enables AI agents to extract structured JSON from invoices and receipts in PDF and image formats using Claude Vision. Supports full document parsing, line item

автор: knportal

GitHub

Описание

Enables AI agents to extract structured JSON from invoices and receipts in PDF and image formats using Claude Vision. Supports full document parsing, line item extraction, validation, and batch CSV export with API key or cryptocurrency payment options.

README

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

smithery badge License: MIT Version MCP

Listed on: Glama · Smithery · mcp.so

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	Description	Price
`parse_invoice`	Full invoice parsing (vendor, line items, totals, due date)	$0.05/call
`parse_receipt`	Retail receipt parsing (merchant, items, tax, payment method)	$0.05/call
`extract_line_items`	Just the itemized list, nothing else	$0.01/call
`extract_totals`	Just subtotal, tax, total, due date	$0.01/call
`validate_invoice`	Math validation — checks that line items add up	$0.01/call
`export_to_csv`	Batch parse multiple files → summary CSV (max 20)	$0.10/call

Tool Reference

`parse_invoice`

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

Parameters

Parameter	Type	Required	Description
`file_path`	string	Yes	Absolute path to the invoice PDF or image (PNG, JPG, WEBP).
`api_key`	string	No*	Your InvoiceParser API key. Get one at plenitudo.ai.
`payment_proof`	string	No*	x402 payment proof (Base USDC tx hash). Alternative to `api_key`.

*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

Parameter	Type	Required	Description
`file_path`	string	Yes	Absolute path to the receipt PDF or image (PNG, JPG, WEBP).
`api_key`	string	No*	Your InvoiceParser API key.
`payment_proof`	string	No*	x402 payment proof (Base USDC tx hash).

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

Parameter	Type	Required	Description
`file_path`	string	Yes	Absolute path to the invoice or receipt PDF or image.
`api_key`	string	No*	Your InvoiceParser API key.
`payment_proof`	string	No*	x402 payment proof (Base USDC tx hash).

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

Parameter	Type	Required	Description
`file_path`	string	Yes	Absolute path to the invoice or receipt PDF or image.
`api_key`	string	No*	Your InvoiceParser API key.
`payment_proof`	string	No*	x402 payment proof (Base USDC tx hash).

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

Parameter	Type	Required	Description
`file_path`	string	Yes	Absolute path to the invoice PDF or image.
`api_key`	string	No*	Your InvoiceParser API key.
`payment_proof`	string	No*	x402 payment proof (Base USDC tx hash).

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

Parameter	Type	Required	Description
`file_paths`	array of strings	Yes	List of absolute paths to invoice/receipt PDFs or images. Maximum 20.
`output_path`	string	Yes	Absolute path where the output CSV file will be saved.
`api_key`	string	No*	Your InvoiceParser API key.
`payment_proof`	string	No*	x402 payment proof (Base USDC tx hash).

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?ref=readme"
    }
  }
}

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

Variable	Required	Description
`ANTHROPIC_API_KEY`	Yes	Anthropic API key for Claude Vision. Set to `maxproxy` for local proxy routing.
`ANTHROPIC_BASE_URL`	No	Override Anthropic base URL. Set to `http://localhost:3456` when using maxproxy locally. Leave unset in cloud deployments.
`CLAUDE_MODEL`	No	Claude model ID. Defaults to `claude-3-5-sonnet-20241022`.
`INVOICEPARSER_DATA_DIR`	No	Directory for SQLite databases. Defaults to `./data`.
`PORT`	No	HTTP port. Defaults to `8000`. Railway sets this automatically.

Deployment (Railway)

Fork this repo
Connect to Railway → New Project → Deploy from GitHub
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
Add a persistent volume at /data
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

Как установить

Добавь это в claude_desktop_config.json и перезапусти Claude Desktop.

{
  "mcpServers": {
    "invoice-parser-mcp": {
      "command": "npx",
      "args": []
    }
  }
}

Invoice Parser

Описание

README

What it does

Tools

Tool Reference

`parse_invoice`

`parse_receipt`

`extract_line_items`

`extract_totals`

`validate_invoice`

`export_to_csv`

Supported formats

Authentication

Usage (Claude Desktop / MCP client)

Architecture

Deployment (Railway)

Running locally (optional maxproxy routing)

Contributing & Security

License

Как установить

Похожие MCP

Stripe

malamutemayhem/unclick-agent-native-endpoints

whiteknightonhorse/APIbase

trackerfitness729-jpg/sitelauncher-mcp-server

Command Palette

Invoice Parser

Описание

README

What it does

Tools

Tool Reference

parse_invoice

parse_receipt

extract_line_items

extract_totals

validate_invoice

export_to_csv

Supported formats

Authentication

Usage (Claude Desktop / MCP client)

Architecture

Deployment (Railway)

Running locally (optional maxproxy routing)

Contributing & Security

License

Как установить

Похожие MCP

Stripe

malamutemayhem/unclick-agent-native-endpoints

whiteknightonhorse/APIbase

trackerfitness729-jpg/sitelauncher-mcp-server

`parse_invoice`

`parse_receipt`

`extract_line_items`

`extract_totals`

`validate_invoice`

`export_to_csv`