Facturas Inbox MCP server

facturas-inbox-mcp

An MCP server that turns a folder of Spanish business documents into validated, structured data an AI agent can reason over. It classifies each PDF (factura, rectificativa, ticket, nómina, modelo AEAT…), extracts the invoice fields (NIF/CIF, base imponible, IVA per rate, IRPF, total), checks the arithmetic and the tax-ID checksums, and computes the IVA soportado / repercutido position for a quarter.

Local and offline. No API keys. It reads only the folders you give it.

Built for the everyday job of a Spanish gestoría: a client drops a month of PDFs in a folder and

someone has to work out what is what, what adds up and what the VAT position is.

30-second demo

Claude Code, Sonnet, pointed at the synthetic examples/inbox (11 documents, including a wrong total, a ticket, a credit note, a payslip, a modelo 303 and a scanned page). Real session; the answer is trimmed for length (full, unedited transcript in docs/demo-transcript.md):

> I'm the bookkeeper for Gestoría Demo Ficticia SL (CIF B87654323). Process the invoice
  inbox and tell me our IVA position for Q3 2026, and flag anything I need to look at
  by hand. Answer in English, briefly.

  ⏺ facturas - scan_folder {}
  ⏺ facturas - vat_summary {"own_tax_id":"B87654323","quarter":"2026-Q3"}
  ⏺ facturas - validate_tax_id {"tax_id":"B87654323"}

Q3 2026 IVA position: €243.00 to pay (a pagar), provisional.

- IVA repercutido: €504.00, from 1 issued invoice (GD-2026-0088, base €2,400 at 21%)
- IVA soportado: €261.00, from 4 received documents (base €1,400): €231 at 21% and
  €30 at 10%
- The July papelería invoice (€52.50 IVA) is cancelled out by the September credit note.

Check by hand:
1. Papelería PE-2026/0455 (30 Jul): the total says €1,250 but base + IVA comes to
   €1,210. Excluded. If the supplier corrects it, your position drops to about €33.
2. Gasolinera ticket 88213 (14 Aug, €60): IVA not broken out and no recipient NIF.
   Excluded. Probably not deductible without a full invoice.
3. Scanned PDF (5 Sep): no text layer, so it needs OCR or a manual read. It could be
   a missing Q3 invoice.
4. Credit note PE-2026/R-0019: classified at 0.69 confidenc

5 turns · 23 s · $0.13. Every number comes from a tool result, not from the model doing arithmetic. Documents that fail a check are excluded and listed with a reason, so nothing is silently counted or silently dropped.

Tools

Shortened. The full README is on GitHub.