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 confidence. Confirm it really is a
   rectificativa of PE-2026/0412.
5. Laura's advisory invoice (3 Aug): €150 IRPF withheld, which goes on modelo 111,
   not the IVA return.
   …

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

Every tool publishes an outputSchema and returns structuredContent, and the SDK validates both directions. All tools set full annotations (readOnlyHint, destructiveHint: false, idempotentHint, openWorldHint: false), so clients can auto-approve the read-only ones.

The checks

extract_invoice returns status: "ok" only when every check passes:

All arithmetic is in integer cents.

Install

Requires Node.js 20.12 or newer.

Try it in 30 seconds (bundled sample data)

claude mcp add facturas-demo -- npx -y facturas-inbox-mcp --demo

--demo serves the synthetic inbox that ships with the package. Then ask Claude: "I'm the bookkeeper for CIF B87654323. What's our IVA position for Q3 2026, and what should I check by hand?"

Claude Code

claude mcp add facturas -- npx -y facturas-inbox-mcp ~/Documents/facturas

Claude Desktop

Add this to claude_desktop_config.json (Settings → Developer → Edit Config):

{
  "mcpServers": {
    "facturas": {
      "command": "npx",
      "args": ["-y", "facturas-inbox-mcp", "/Users/you/Documents/facturas"]
    }
  }
}

Any other MCP client

It's a standard stdio server: npx -y facturas-inbox-mcp <folder> [more folders…], or npx -y facturas-inbox-mcp --demo. Folders can also come from FACTURAS_INBOX_DIRS (separated like PATH).

From source, with the sample inbox

git clone https://github.com/pedrozapatadev/facturas-inbox-mcp && cd facturas-inbox-mcp
npm install && npm run build
claude mcp add facturas -- node "$PWD/dist/index.js" "$PWD/examples/inbox"

Then ask: "I'm the bookkeeper for CIF B87654323. What's our IVA position for Q3 2026?"

To poke at the tools without an LLM, run npm run inspect (MCP Inspector).

Design decisions

• Deterministic core, no model inside. The agent is already a language model. What it lacks are tools whose answers it can trust. Extraction is rule-based and every result carries its evidence: classifier signals, check details, warnings. The server can explain itself, and the same input always gives the same output.
• Fail loudly, not silently. Fields that weren't found are null, not guessed. Documents that fail a check are excluded from totals and listed with the reason. Errors are returned as isError results that say how to fix the call ("Pass force: true to try anyway", "Run OCR first").
• Token-efficient. scan_folder returns compact rows and paginates. extract_invoice is concise by default. export_csv returns a path and counts, not the data.
• Sandboxed filesystem. Paths are resolved with realpath and must sit inside a folder given at startup, so ../ traversal and symlinks that point outside are rejected (and tested). The only write is export_csv, which creates new .csv files and never overwrites.
• Untrusted document text. The server instructions tell the agent never to follow instructions found inside a document. Raw text is only returned on request, labelled untrusted_text_preview. CSV cells that start with =, +, - or @ are neutralized against spreadsheet formula injection. Exports are created 0600.
• Bounded work per document. Files are limited to 20 MB and PDFs to 200 pages. Text is cut at 1M characters before analysis. The extraction regexes are linear-time; a ReDoS case has a regression test.
• Threat model. The attacker controls document contents, not the filesystem. Paths that are missing and paths outside the folders get the same error, so the tool can't be used to probe what exists elsewhere. Someone who can already write to the inbox could race the check-then-read (a TOCTOU window); that is out of scope.
• stdout is the protocol. All logging goes to stderr. An end-to-end test drives the built binary over real stdio, and it would fail on a stray console.log.

Limitations

Honest scope. This is a showcase-sized tool, not accounting software.

• PDFs need a text layer. Scanned images are reported as unreadable with an OCR hint (e.g. ocrmypdf); there is no built-in OCR.
• Heuristic extraction tuned to common Spanish invoice layouts (labelled fields like Base imponible, IVA 21 %, Total factura). Unusual layouts come back as needs_review rather than wrong.
• Not handled yet: recargo de equivalencia, intra-EU / reverse-charge invoices, Facturae XML, and counterparty names (only tax IDs).
• Checksum validation only. A valid NIF is well-formed; it is not confirmed as registered with AEAT or VIES.
• Not an e-invoicing or VeriFactu tool. It reads received paperwork; it does not issue invoices or file returns. vat_summary is a working figure for review, not a modelo 303.

Development

npm install
npm run fixtures    # regenerate examples/inbox (synthetic data, valid-checksum fictional IDs)
npm run typecheck
npm test            # unit + in-memory MCP client + stdio end-to-end (build first for the e2e)
npm run build
npm run inspect     # MCP Inspector UI against the sample inbox

src/
  index.ts        stdio entry point, CLI args → allowed folders
  server.ts       the six tools: schemas, annotations, error mapping
  schemas.ts      zod input/output schemas
  pipeline.ts     read → classify → extract, shared by all tools
  classify.ts     rule-based document classifier with explainable signals
  extract.ts      invoice field extraction + arithmetic checks
  taxid.ts        NIF / NIE / CIF validation
  amounts.ts      Spanish amounts and dates, in integer cents
  vat-summary.ts  repercutido / soportado aggregation
  documents.ts    sandboxed filesystem + PDF text extraction
  csv.ts          Excel-friendly CSV export
test/             MCP-level tests (in-memory client, stdio e2e, sandbox escapes)

Built on the official MCP TypeScript SDK v2 (@modelcontextprotocol/server), zod and unpdf.

Releasing

1. Bump version in package.json and both version fields in server.json.
2. npm publish (runs build + tests first; needs npm 2FA).
3. gh workflow run publish-mcp-registry.yml lists the new version in the MCP Registry via GitHub OIDC (no secrets).

Roadmap

• Optional OCR pass for scanned documents
• Counterparty names, recargo de equivalencia, intra-EU invoices
• Facturae XML input
• VIES lookup as an opt-in, clearly network-marked tool
• Streamable HTTP transport for remote deployment

License

MIT © 2026 Pedro Zapata Medal. All sample documents are synthetic: the companies, people and tax IDs are fictional.