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 AI tools installable in one line — document parsing, anomaly detection on received invoices, multi-invoice reporting, Italian and EU VAT verification via VIES, structural XML checks and offline SDI error lookup.

Status: beta. See Known limitations before relying on validation results.

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

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"],
      "env": { "FATTURAPA_ALLOWED_ROOTS": "/path/to/your/invoices" }
    }
  }
}

FATTURAPA_ALLOWED_ROOTS lists the only folders the server may read (: separated on macOS/Linux, ; on Windows). Without it every file_path read is refused and documents must be passed as xml_content. This is deliberate: the server is driven by an AI agent reading untrusted documents.

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

Known limitations (v0.3.2)

An audit against the official AdE schema (FatturaPA v1.2.3) with synthetic invoices found the following. They are being fixed in the next releases; until then:

• validate_invoice is structural only. The bundled XSD files are stubs: an invoice with an unknown document type (TD99), an invalid currency (EURO) or missing mandatory blocks is reported as valid: true. Do not use it as a substitute for SDI validation.
• lookup_sdi_error: several codes have descriptions that differ from the official list (e.g. 00001 is "invalid file name"), and some codes are missing.
• Batches (lots): when a file contains more than one invoice, only the first one is fully analysed.
• Encoding: XML declared as ISO-8859-1 / windows-1252 may be decoded incorrectly.
• .p7m signed files are not supported yet: extract the XML first.
• Report: credit notes (TD04) are added instead of subtracted; totals across different currencies are summed.
• Amounts are returned as floats.

What is solid today: coherence checks (totals, VAT, P.IVA checksum, dates), fail-closed file access, XXE protection, VIES degradation when the service is down.

Changelog / Release history

v0.3.2 stats: 7 tools · 181 tests · 95% coverage, including server startup

What it demonstrates

• MCP server with strict mypy typing, tested on Python 3.11, 3.12 and 3.13
• Automated security audit — bandit + pip-audit
• Guaranteed 80% minimum coverage (currently 95% across 181 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.

Project status

Beta. Tested with synthetic FatturaPA documents checked against the official schema; not yet used in production. See Known limitations. 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 installabili in una riga — parsing del documento, rilevamento anomalie sulle fatture ricevute, report multi-fattura, verifica P.IVA italiana ed europea via VIES, controlli strutturali dell'XML e lookup errori SDI offline.

Stato: beta. Leggere i Limiti noti prima di fare affidamento sui risultati della validazione.

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

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"],
      "env": { "FATTURAPA_ALLOWED_ROOTS": "C:\\percorso\\delle\\fatture" }
    }
  }
}

FATTURAPA_ALLOWED_ROOTS indica le sole cartelle che il server può leggere (separate da ; su Windows, da : su macOS/Linux). Senza questa variabile ogni lettura da file_path viene rifiutata e le fatture vanno passate come xml_content. È una scelta voluta: il server è pilotato da un agente AI che legge documenti non fidati.

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

Limiti noti (v0.3.2)

Un audit contro lo schema ufficiale AdE (FatturaPA v1.2.3) con fatture sintetiche ha evidenziato i punti seguenti, in correzione nelle prossime release:

• validate_invoice è solo strutturale. Gli XSD inclusi sono stub: una fattura con tipo documento inesistente (TD99), divisa non valida (EURO) o blocchi obbligatori mancanti risulta valid: true. Non sostituisce la validazione dello SDI.
• lookup_sdi_error: alcune descrizioni non corrispondono all'elenco ufficiale (es. 00001 è "nome file non valido") e alcuni codici mancano.
• Lotti: se un file contiene più fatture, solo la prima viene analizzata del tutto.
• Encoding: XML dichiarati ISO-8859-1 / windows-1252 possono essere decodificati male.
• .p7m: i file firmati non sono ancora supportati; estrarre prima l'XML.
• Report: le note di credito (TD04) vengono sommate invece che sottratte; totali in valute diverse vengono sommati.
• Gli importi sono restituiti come float.

Già solido oggi: controlli di coerenza (totali, IVA, checksum P.IVA, date), accesso ai file fail-closed, protezione XXE, gestione di VIES quando il servizio non risponde.

Changelog / Storico release

Statistiche v0.3.2: 7 tool · 181 test · 95% di coverage, avvio del server incluso

Cosa dimostra tecnicamente

• MCP server con strict typing mypy, testato su Python 3.11, 3.12 e 3.13
• Security audit automatico — bandit + pip-audit
• Coverage minima garantita all'80% (attualmente 95% su 181 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.

Stato del progetto

Beta. Testato con fatture FatturaPA sintetiche verificate contro lo schema ufficiale; non ancora usato in produzione. Vedi Limiti noti. 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