SDI

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:

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.