fatturapa-mcp-server 0.3.0

MCP server for Italian FatturaPA/SDI e-invoicing

fatturapa-mcp-server

---

English

The problem

Every project integrating FatturaPA reimplements the same validation, parsing and SDI error handling from scratch. The result: weeks of repeated work, hidden bugs and no standardization.

The solution

Seven production-grade AI tools installable in one line — official AdE XSD validation, full document parsing, offline SDI error lookup, Italian and EU VAT verification via VIES, anomaly detection and multi-invoice reporting.

Who is it for

Python developers and AI teams working on Italian electronic invoicing systems who want to integrate Claude without reimplementing FatturaPA compliance from scratch on every project.

What is this?

An MCP (Model Context Protocol) server that gives AI assistants seven ready-to-use tools for working with Italian electronic invoices (FatturaPA) and the SDI (Sistema di Interscambio) system — no plumbing required.

Tools

Tool	Input	What it does
validate_invoice	xml_content	Validates FatturaPA XML against official AdE XSD schemas (v1.2 & v1.3); auto-detects version from namespace
extract_invoice_data	xml_content	Extracts supplier, customer, amounts, line items and metadata from a valid FatturaPA document
lookup_sdi_error	error_code	Returns the official Italian description, category and resolution hint for any SDI error code (offline)
check_piva	piva	Validates an Italian P.IVA (VAT number) using the official MEF checksum algorithm — no network call
verify_piva_vies	country_code, vat_number	Verifies any EU VAT number against the live VIES REST API; degrades gracefully when the service is down
find_invoice_anomalies	xml_content	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	xml_contents	Aggregates multiple FatturaPA XML documents into a single report with statistics, supplier/customer breakdown and anomaly summary

Quick start

Option A — uvx (no install required)

uvx fatturapa-mcp-server

Option B — pip

pip install fatturapa-mcp-server
fatturapa-mcp-server

Claude Desktop configuration

Add the following block to your Claude Desktop config file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "fatturapa": {
      "command": "uvx",
      "args": ["fatturapa-mcp-server"]
    }
  }
}

After restarting Claude Desktop you will see seven new tools in the tool panel.

Note on XSD schemas: validate_invoice requires the official AdE XSD files. See src/fatturapa_mcp/schemas/README.md for download instructions.

Changelog / Release history

Wave	Tools / Features	Release
Wave 1	validate_invoice, extract_invoice_data, lookup_sdi_error, check_piva, verify_piva_vies	v0.1.0
Wave 2	PyPI publication, CI/CD, security audit, full coverage	v0.1.0
Wave 3	Context propagation, structured logging, progress reporting, roots-based secure file access	v0.1.x
Wave 4	find_invoice_anomalies, generate_invoice_report	v0.2.0

v0.3.0 stats: 7 tools · 178 tests · 95.6% coverage

What it demonstrates

• Production-grade MCP server with strict mypy typing
• Automated security audit — bandit + pip-audit
• Guaranteed 80% minimum coverage (currently 95.6% across 178 tests)
• Fail-closed file-system access: reads are refused unless explicitly configured
• Published on PyPI — installable anywhere in one line
• Bilingual IT/EN — built for Italian and international market

Auditable by design

Every feature in this repository was built through a governed multi-agent pipeline — planner, executor and reviewer as separate roles, each with declared authority and hard quality gates between them.

The coord/ directory is the audit trail. One handoff per task, recording the files changed and why, the commands run with their PASS/FAIL output, the assumptions made and how they were verified, and the risks left open. Fifteen handoffs cover the four development waves listed above.

For regulated work — e-invoicing, tax data, compliance — being able to show how a system was built matters as much as showing that it works. The methodology is documented separately in agentic-dev-pipeline.

Production status

Used on real Italian electronic invoicing systems. Tested with real SDI documents in production environments. Part of a broader ecosystem: fatturapa-mcp-server → sdi-ops-monitor

Development setup

git clone https://github.com/MaurizioLisanti/fatturapa-mcp-server
cd fatturapa-mcp-server

# Install the package and all dev dependencies
make install        # pip install -e ".[dev]"

# Run the full quality gate (lint + typecheck + tests + security)
make check

Individual targets:

make test           # pytest with coverage (fail-under 80 %)
make lint           # ruff check + ruff format --check
make typecheck      # mypy --strict
make security       # bandit -ll + pip-audit
make format         # auto-fix formatting and imports

MCP Inspector

MCP Inspector lets you call tools interactively from a local web UI — useful during development:

npx @modelcontextprotocol/inspector uvx fatturapa-mcp-server
# Open http://localhost:5173 in your browser

Related projects

• sdi-ops-monitor — AWS-based pipeline that receives, stores and routes FatturaPA files from/to SDI. Use together with this MCP server to give Claude end-to-end visibility into your Italian e-invoicing operations.

• agentic-dev-pipeline — The governed multi-agent development pipeline this project was built with. The handoffs in coord/ are its output.

---

Italiano

Il problema

Ogni progetto che integra FatturaPA reimplementa da zero la stessa logica di validazione, parsing e gestione errori SDI. Il risultato: settimane di lavoro ripetuto, bug nascosti e nessuna standardizzazione.

La soluzione

Sette tool AI production-grade installabili in una riga — validazione XSD ufficiale AdE, parsing completo, lookup errori SDI offline, verifica P.IVA italiana ed europea via VIES, rilevamento anomalie e report multi-fattura.

Per chi è

Developer Python e team AI che lavorano su sistemi di fatturazione elettronica italiana e vogliono integrare Claude senza reimplementare la compliance FatturaPA da zero ad ogni progetto.

Cos'è questo progetto?

Un server MCP (Model Context Protocol) che fornisce agli assistenti AI sette strumenti pronti all'uso per lavorare con le fatture elettroniche italiane (FatturaPA) e il Sistema di Interscambio (SDI).

Strumenti disponibili

Strumento	Input	Cosa fa
validate_invoice	xml_content	Valida un XML FatturaPA contro gli XSD ufficiali AdE (v1.2 e v1.3); rileva automaticamente la versione dal namespace
extract_invoice_data	xml_content	Estrae fornitore, cliente, importi, righe dettaglio e metadati da un documento FatturaPA valido
lookup_sdi_error	error_code	Restituisce la descrizione ufficiale italiana, la categoria e il suggerimento di risoluzione per qualsiasi codice errore SDI (offline)
check_piva	piva	Valida una P.IVA italiana tramite l'algoritmo di checksum ufficiale MEF — nessuna chiamata di rete
verify_piva_vies	country_code, vat_number	Verifica qualsiasi partita IVA UE contro l'API REST VIES in tempo reale; risponde in modo degradato se il servizio è irraggiungibile
find_invoice_anomalies	xml_content	Rileva anomalie in un documento FatturaPA XML: totale incoerente, IVA errata, data futura, P.IVA invalida, destinatario mancante, righe incomplete, importo negativo, pagamento mancante
generate_invoice_report	xml_contents	Aggrega più documenti FatturaPA XML in un unico report con statistiche, riepilogo fornitori/clienti e analisi delle anomalie

Avvio rapido

Opzione A — uvx (nessuna installazione necessaria)

uvx fatturapa-mcp-server

Opzione B — pip

pip install fatturapa-mcp-server
fatturapa-mcp-server

Configurazione Claude Desktop

Aggiungere il seguente blocco al file di configurazione di Claude Desktop:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "fatturapa": {
      "command": "uvx",
      "args": ["fatturapa-mcp-server"]
    }
  }
}

Dopo il riavvio di Claude Desktop, i sette strumenti compariranno nel pannello degli strumenti.

Nota sugli XSD: validate_invoice richiede i file XSD ufficiali di AdE. Vedere src/fatturapa_mcp/schemas/README.md per le istruzioni di download.

Changelog / Storico release

Wave	Tool / Funzionalità	Release
Wave 1	validate_invoice, extract_invoice_data, lookup_sdi_error, check_piva, verify_piva_vies	v0.1.0
Wave 2	Pubblicazione PyPI, CI/CD, security audit, coverage completa	v0.1.0
Wave 3	Propagazione contesto, logging strutturato, progress reporting, accesso file sicuro via roots	v0.1.x
Wave 4	find_invoice_anomalies, generate_invoice_report	v0.2.0

Statistiche v0.3.0: 7 tool · 178 test · 95.6% coverage

Cosa dimostra tecnicamente

Cosa dimostra tecnicamente

• MCP server production-grade con strict typing mypy
• Security audit automatico — bandit + pip-audit
• Coverage minima garantita all'80% (attualmente 95.6% su 178 test)
• Accesso al filesystem fail-closed: le letture sono negate salvo configurazione esplicita
• Pubblicato su PyPI — installabile ovunque con una riga
• Bilingue IT/EN — pensato per mercato italiano e internazionale

Tracciabilita by design

Ogni funzionalita di questo repository e stata costruita con una pipeline multi-agente governata — planner, executor e reviewer come ruoli distinti, ciascuno con autorita dichiarata e quality gate obbligatori tra una fase e l'altra.

La cartella coord/ e la pista di controllo. Un handoff per task, con i file modificati e il motivo, i comandi eseguiti con esito PASS/FAIL, le assunzioni fatte e come sono state verificate, i rischi lasciati aperti. Quindici handoff coprono le quattro wave di sviluppo elencate sopra.

Nel lavoro su ambiti regolati — fatturazione elettronica, dati fiscali, compliance — poter mostrare come un sistema e stato costruito conta quanto mostrare che funziona. La metodologia e documentata separatamente in agentic-dev-pipeline.

In produzione

Usato su sistemi reali di fatturazione elettronica italiana. Testato con documenti SDI reali in ambiente di produzione. Parte di un ecosistema più ampio: fatturapa-mcp-server → sdi-ops-monitor

Setup per lo sviluppo

git clone https://github.com/MaurizioLisanti/fatturapa-mcp-server
cd fatturapa-mcp-server

# Installa il pacchetto e tutte le dipendenze di sviluppo
make install        # pip install -e ".[dev]"

# Esegui il quality gate completo (lint + typecheck + test + security)
make check

Target individuali:

make test           # pytest con coverage (fail-under 80 %)
make lint           # ruff check + ruff format --check
make typecheck      # mypy --strict
make security       # bandit -ll + pip-audit
make format         # correzione automatica formattazione e import

MCP Inspector

MCP Inspector permette di invocare gli strumenti in modo interattivo da una web UI locale — utile durante lo sviluppo:

npx @modelcontextprotocol/inspector uvx fatturapa-mcp-server
# Aprire http://localhost:5173 nel browser

Progetti correlati

• sdi-ops-monitor — Pipeline AWS per ricevere, archiviare e instradare i file FatturaPA da/verso il SDI. Da usare insieme a questo server MCP per dare a Claude visibilità end-to-end sulle operazioni di fatturazione elettronica italiana.

• agentic-dev-pipeline — La pipeline di sviluppo multi-agente governata con cui questo progetto è stato costruito. Gli handoff in coord/ ne sono l'output.

---

License / Licenza

MIT