# facturas-inbox-mcp [Health: Active]

**Category:** 💻 Developer Tools  
**Repository:** https://github.com/pedrozapatadev/facturas-inbox-mcp  
**GitHub Stars:** 0  
**npm Downloads (last month):** 271  
**Views:** 0  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/facturas-inbox-mcp

## Description
Spanish invoice PDFs to validated data: NIF/IVA/IRPF extraction, arithmetic checks, IVA per quarter.

## Tools
Capabilities this server exposes over MCP:

- **scan_folder** — Classify and extract every document in a folder; one compact row each, paginated with `limit` / `cursor
- **classify_document** — Label one document, with a confidence score and the signals behind the label
- **extract_invoice** — Invoice number, date, issuer/recipient NIF, base, VAT lines, IRPF, total, plus every cross-check. `response_format: concise \
- **validate_tax_id** — NIF / NIE / CIF checksum validation. Says the expected control character when wrong
- **vat_summary** — IVA repercutido vs. soportado for a `quarter` (`2026-Q3`) or a `from`/`to` range, by rate, with the exclusions listed
- **export_csv** — Write the scan to a new `.csv` file (`;`-separated, decimal comma, opens directly in Spanish Excel). Never overwrites

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `npx` (confidence: high):

```json
"mcpServers": {
  "facturas-inbox-mcp": {
    "command": "npx",
    "args": ["-y","facturas-inbox-mcp"],
    "env": {
      "FACTURAS_INBOX_DIRS": ""
    }
  }
}
```

**Requires environment variables:** `FACTURAS_INBOX_DIRS` — the values above are empty placeholders; fill in real credentials before running (see the repository for what each one is for).

## Documentation

## 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:

```bash
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.

_Full upstream README: https://allmcps.com/mcp/facturas-inbox-mcp/readme_