# FatturaPA / SDI [Health: Active]

**Category:** 💰 Finance & Fintech  
**Repository:** https://github.com/MaurizioLisanti/fatturapa-mcp-server  
**GitHub Stars:** 0  
**Views:** 0  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/fatturapa-sdi

## Description
Italian e-invoicing (FatturaPA/SDI): parse invoices, detect anomalies, VAT checks via VIES, reports.

## Tools
Capabilities this server exposes over MCP:

- **validate_invoice** — Checks that the XML is well-formed and has the FatturaPA root structure. ⚠️ **Not yet a full schema validation** — see Known limitations
- **extract_invoice_data** — Extracts supplier, customer, amounts, line items and metadata from a valid FatturaPA document
- **lookup_sdi_error** — Returns description, category and resolution hint for SDI error codes (offline). ⚠️ The table is being realigned with the official list — see Known limitations
- **check_piva** — Validates an Italian P.IVA (VAT number) using the official MEF checksum algorithm — no network call
- **verify_piva_vies** — Verifies any EU VAT number against the live VIES REST API; degrades gracefully when the service is down
- **find_invoice_anomalies** — Detects anomalies in a FatturaPA XML document: inconsistent totals, wrong VAT, future dates, invalid P.IVA, missing recipient, incomplete line items, negative amounts, missing payment info
- **generate_invoice_report** — Aggregates multiple FatturaPA XML documents into a single report with statistics, supplier/customer breakdown and anomaly summary

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

```json
"mcpServers": {
  "sdi": {
    "command": "uvx",
    "args": ["fatturapa-mcp-server"],
    "env": {
      "FATTURAPA_ALLOWED_ROOTS": ""
    }
  }
}
```

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

## Documentation

## What FatturaPA / SDI does

The FatturaPA / SDI MCP server exposes seven tools for working with Italian electronic invoices and VAT identifiers. It can check whether an XML document is well formed and has the expected FatturaPA root structure, extract supplier, customer, totals, line items, and metadata, and identify common invoice inconsistencies.

Its analysis includes mismatched totals, incorrect VAT calculations, dates in the future, invalid Italian VAT numbers, missing recipients, incomplete line items, negative amounts, and absent payment information. It can also combine several invoice documents into a report containing statistics, supplier and customer groupings, and an anomaly summary.

VAT operations cover two paths. `check_piva` applies the official Italian MEF checksum algorithm locally, while `verify_piva_vies` sends an EU VAT-number check to the VIES REST API and handles service outages without failing abruptly. `lookup_sdi_error` provides an offline description, category, and suggested resolution for an SDI error code.

This project belongs in the 💰 Finance & Fintech category and is aimed at Python developers and AI teams integrating Italian e-invoicing workflows.

## How it works

The server runs as a local MCP process and can be started through `uvx fatturapa-mcp-server` or after installing the package with pip. Tools can receive XML content directly. File reads are restricted to directories listed in `FATTURAPA_ALLOWED_ROOTS`; paths outside those directories are refused. If the variable is not set, callers must provide the document as XML content instead.

The server is designed for untrusted invoice documents and uses fail-closed file access and XXE protection. Most checks are local. VIES verification is the exception: it depends on the external VIES REST service and degrades gracefully when that service is unavailable.

## Setup and configuration

Install without a separate package setup using:

```bash
uvx fatturapa-mcp-server
```

Alternatively, install it with `pip install fatturapa-mcp-server` and run `fatturapa-mcp-server`. For file-based workflows, set `FATTURAPA_ALLOWED_ROOTS` to the permitted folders. Separate multiple paths with `:` on macOS or Linux and `;` on Windows.

Claude Desktop can launch the server with a configuration that uses `uvx` as the command and `fatturapa-mcp-server` as its argument. MCP Inspector can also be used to call the tools through a local browser interface during development.

## Tools and capabilities

- `validate_invoice`: checks XML well-formedness and the FatturaPA root structure.
- `extract_invoice_data`: reads parties, amounts, lines, and document metadata.
- `lookup_sdi_error`: looks up SDI error information from an offline table.
- `check_piva`: checks an Italian P.IVA checksum without network access.
- `verify_piva_vies`: verifies an EU VAT number through VIES.
- `find_invoice_anomalies`: reports invoice consistency and completeness issues.
- `generate_invoice_report`: summarizes multiple FatturaPA XML documents.

## Limitations and notes

The FatturaPA / SDI MCP server is beta software and has not yet been used in production. `validate_invoice` currently performs structural checks only; its bundled XSD files are stubs and it must not replace official SDI validation. The offline SDI error table is also being aligned with the official list, so descriptions may differ and some codes may be absent.

For files containing multiple invoices, only the first invoice is fully analyzed. ISO-8859-1 and Windows-1252 declarations may be decoded incorrectly, and signed `.p7m` files must be extracted to XML before processing. Reports currently add credit notes instead of subtracting them and combine totals across currencies. Returned amounts are represented as floats. VIES checks depend on the availability of the external service.

_Full upstream README: https://allmcps.com/mcp/fatturapa-sdi/readme_