Facturas Inbox MCP

What facturas-inbox-mcp does

facturas-inbox-mcp turns a folder of Spanish business PDFs into structured results for an MCP client. It can identify invoices, rectifying invoices, tickets, payslips, AEAT forms, and other document types, then extract invoice number, date, issuer and recipient tax IDs, taxable base, VAT by rate, IRPF withholding, and total.

The server checks the extracted data rather than asking the language model to perform the arithmetic. It validates NIF, NIE, and CIF control characters; checks supported Spanish VAT rates; compares base, VAT, withholding, and total values; and reports the evidence or warning associated with each result. Documents that fail validation are omitted from VAT calculations and listed with the reason.

How it works

The package is a local, deterministic Node.js MCP server. It requires Node.js 20.12 or later and communicates through standard input and output. It reads only folders supplied at startup, either as command-line arguments or through FACTURAS_INBOX_DIRS. No external API key or hosted service is required.

scan_folder processes a directory and returns compact rows with pagination through limit and cursor. Individual files can be examined with classify_document and extract_invoice. vat_summary calculates IVA repercutido and soportado for a quarter such as 2026-Q3, or for a custom date range, grouped by rate and accompanied by exclusions. validate_tax_id can also report the expected control character when a tax ID is invalid.

Setup and configuration

Install or run the package with npx, for example:

npx -y facturas-inbox-mcp /path/to/invoices

Multiple folders can be passed. The bundled --demo option serves the synthetic sample inbox. A source installation uses npm install followed by npm run build, after which the compiled entry point can be started with Node.js. The repository also documents configuration for Claude Desktop and Claude Code, and npm run inspect can connect the built server to MCP Inspector.

The server resolves paths against the configured folders and rejects traversal or symlinks that point outside them. export_csv is the sole writing operation: it creates a new semicolon-separated CSV with decimal commas, suitable for Spanish Excel, and does not overwrite an existing file. CSV values that could be interpreted as spreadsheet formulas are neutralized.

Tools and capabilities

• scan_folder: classify and extract all documents in a folder with compact, paginated output.
• classify_document: return a document label, confidence score, and classification signals.
• extract_invoice: return invoice fields, cross-check results, warnings, and either concise or detailed output.
• validate_tax_id: check NIF, NIE, or CIF checksum validity.
• vat_summary: calculate VAT by rate for a quarter or date range and show excluded documents.
• export_csv: write a new scan export for spreadsheet use.

All tools publish output schemas and structured content. Read-only operations are annotated as non-destructive and idempotent, allowing compatible clients to use those hints for approval behavior.

Limitations and notes

facturas-inbox-mcp expects PDFs with a text layer. Scanned image PDFs are reported as unreadable and require external OCR or manual review; OCR is not built in. Extraction uses heuristics aimed at common Spanish invoice layouts, so unusual formats may return needs_review instead of guessed values.

The project does not currently handle recargo de equivalencia, intra-EU or reverse-charge invoices, or Facturae XML. Files are limited to 20 MB and PDFs to 200 pages, with text capped before analysis. It is a review and extraction aid rather than accounting software, so VAT results should be checked before filing.