mcp-fattura-elettronica-it
This server is an MCP implementation for Italian electronic invoicing (FatturaPA XML v1.6.1), offering 21 tools to manage the full lifecycle of electronic invoices — generation, validation, parsing, and analysis — conforming to SDI/Agenzia delle Entrate specifications, with no external API calls required.
Transmission & Header
Build DatiTrasmissione blocks with SDI codes, PEC addresses, and
ProgressivoInvioidentifiersValidate seller (
CedentePrestatore) and buyer (CessionarioCommittente) blocks including VAT numbers, addresses, and fiscal regimesValidate Italian VAT numbers (Partita IVA) with 11-digit format and modulo-10 checksum
Look up and validate
CodiceDestinatario(6-char SDI code) or PEC address format
Invoice Body
Build
DatiGeneraliwith document type (TD01–TD28), date, number, and currencyAdd line items (
DettaglioLinee) with quantity, unit price, VAT rate, and exemption codesAutomatically compute VAT summaries (
DatiRiepilogo) grouped by VAT rate andNaturacodes (N1–N7)Build payment blocks with conditions (TP01–TP03), methods (MP01–MP23), and IBAN
Attach base64-encoded documents (PDF, XML, ZIP, etc.)
Compute withholding tax (
ritenuta d'acconto) with RT01–RT06 type codes
XML Generation & Validation
Assemble all blocks into a complete, standards-compliant FatturaPA XML document
Validate XML against the official XSD schema v1.6.1
Parse existing FatturaPA XML into structured JSON
Export parsed data to clean, indented JSON
Generate the official SDI filename (
IT{PartitaIVA}_{ProgressivoInvio}.xml)
Reference Codes
Retrieve all official code tables:
RegimeFiscale(RF01–RF19),TipoDocumento(TD01–TD28), andNatura(N1–N7) with descriptions and legal references
mcp-fattura-elettronica-it 🇮🇹
Python MCP server for Italian electronic invoicing in FatturaPA XML format (SDI / Agenzia delle Entrate standard, version 1.6.1). It allows AI agents (Claude, IDE) to generate, validate, and analyze B2B, B2G, and cross-border electronic invoices directly compliant with the technical specifications of the Sistema di Interscambio (SDI).
English summary
This is a Model Context Protocol (MCP) server for Italian electronic invoicing. It exposes 21 tools covering the full lifecycle of a FatturaPA XML document: transmission header construction, seller/buyer validation, document type codes (TD01–TD28), line items, VAT summary computation, payment terms, XSD validation against the official Agenzia delle Entrate schema (v1.6.1), XML generation, parsing, JSON export, SDI filename generation, and withholding tax (ritenuta d'acconto) calculation. The server requires no external API calls — all logic runs locally. Licensed under Apache 2.0.
Related MCP server: mcp-ksef-pl
🚀 Installation
Via PyPI (recommended)
pip install mcp-fattura-elettronica-itmcp-einvoicing-core is installed automatically as a dependency.
lxml is also required and included — no extra steps needed.
Without prior installation using uvx:
uvx mcp-fattura-elettronica-itFrom source
git clone https://github.com/cmendezs/mcp-fattura-elettronica-it.git
cd mcp-fattura-elettronica-it
python -m venv .venv
source .venv/bin/activate # Windows: .venv\Scripts\activate
pip install -e ".[dev]"
cp .env.example .env⚙️ Configuration
The server does not require external credentials in v0.1.0. The available environment variables are:
Variable | Description | Default |
| Log level ( |
|
| Path to the FatturaPA XSD file |
|
🤖 Claude Desktop Integration
Add to the claude_desktop_config.json file:
{
"mcpServers": {
"fattura-elettronica-it": {
"command": "uvx",
"args": ["mcp-fattura-elettronica-it"]
}
}
}⌨️ Cursor Integration
Configuration file (~/.cursor/mcp.json or .cursor/mcp.json in the project folder):
{
"mcpServers": {
"fattura-elettronica-it": {
"command": "uvx",
"args": ["mcp-fattura-elettronica-it"]
}
}
}🪐 Kiro Integration
{
"mcpServers": {
"fattura-elettronica-it": {
"command": "uvx",
"args": ["mcp-fattura-elettronica-it"],
"disabled": false,
"autoApprove": []
}
}
}🧰 Available MCP Tools
Header — FatturaElettronicaHeader (7 tools)
Tool | Description |
| Build DatiTrasmissione block: ProgressivoInvio, CodiceDestinatario, PECDestinatario |
| Validate seller block: IdFiscaleIVA, Anagrafica, Sede, RegimeFiscale codes |
| Validate buyer block: IdFiscaleIVA or CodiceFiscale, Sede |
| Return all valid RegimeFiscale codes with descriptions (RF01–RF19) |
| Validate Italian VAT number (Partita IVA) format and checksum (11 digits) |
| Generate a unique ProgressivoInvio identifier (max 10 alphanumeric chars) |
| Return info about a CodiceDestinatario (6-char SDI code) or PEC address |
Body — FatturaElettronicaBody (7 tools)
Tool | Description |
| Build DatiGenerali block: TipoDocumento, Divisa, Data, Numero, Causale |
| Return all TD01–TD28 codes with descriptions and use cases (incl. cross-border) |
| Add a DettaglioLinee entry: NumeroLinea, Descrizione, Quantita, PrezzoUnitario |
| Compute DatiRiepilogo: imponibile, imposta, AliquotaIVA from line items |
| Return all Natura codes (N1–N7 and sub-codes) for VAT exemption with legal references |
| Build DatiPagamento: CondizioniPagamento (TP01/02/03), ModalitaPagamento (MP01–MP23) |
| Attach a base64-encoded document to the Allegati block with name and format |
Global — generation and validation (7 tools)
Tool | Description |
| Generate a complete FatturaPA XML file from structured input data |
| Validate a FatturaPA XML string against the official XSD schema v1.6.1 |
| Parse an existing FatturaPA XML string and return a structured JSON dict |
| Export a parsed FatturaPA structure to clean JSON format |
| Validate Partita IVA format and Luhn-like checksum (11-digit Italian VAT) |
| Generate the official SDI filename: IT{PartitaIVA}_{ProgressivoInvio}.xml |
| Check and compute ritenuta d'acconto (withholding tax) for professional invoices |
Usage examples
Example 1 — Generate a complete B2B invoice
1. validate_partita_iva_format("01234567897")
→ { "valid": true }
2. generate_progressivo_invio(sequence=1)
→ { "progressivo_invio": "00001" }
3. build_transmission_header(id_paese="IT", id_codice="01234567897",
progressivo_invio="00001", formato_trasmissione="FPR12",
codice_destinatario="ABC123")
4. validate_cedente_prestatore(id_paese="IT", id_codice="01234567897",
denominazione="ACME Srl", regime_fiscale="RF01",
indirizzo="Via Roma 1", cap="00100", comune="Roma", nazione="IT")
5. validate_cessionario(denominazione="Buyer Srl",
id_paese="IT", id_codice="98765432109",
indirizzo="Via Verdi 2", cap="20100", comune="Milano")
6. build_dati_generali(tipo_documento="TD01", data="2026-01-15",
numero="2026/001", divisa="EUR")
7. add_linea_dettaglio(numero_linea=1, descrizione="Consulenza informatica",
quantita=8, unita_misura="ORE", prezzo_unitario=100.0,
prezzo_totale=800.0, aliquota_iva=22.0)
8. compute_totali(linee=[{"prezzo_totale": 800.0, "aliquota_iva": 22.0}])
→ { "totale_fattura": "976.00" }
9. build_dati_pagamento(condizioni_pagamento="TP02", modalita_pagamento="MP05",
importo_pagamento=976.0, iban="IT60X0542811101000000123456")
10. generate_fattura_xml(...tutti i blocchi precedenti...)
→ { "xml": "<?xml ...", "filename": "IT01234567897_00001.xml" }
11. validate_fattura_xsd(xml_string=...)
→ { "valid": true }Example 2 — Professional invoice with withholding tax (ritenuta d'acconto)
check_ritenuta_acconto(imponibile=1000.0, tipo_ritenuta="RT02",
causale_pagamento="A")
→ {
"DatiRitenuta": {
"TipoRitenuta": "RT02",
"ImportoRitenuta": "200.00",
"AliquotaRitenuta": "20.00",
"CausalePagamento": "A"
},
"importo_ritenuta": "200.00"
}Example 3 — Consult VAT exemption codes
get_natura_codes()
→ codes: [
{ "code": "N3.1", "description": "Non imponibili — esportazioni",
"legal_ref": "Art. 8 DPR 633/72" },
{ "code": "N6.1", "description": "Inversione contabile — rottami",
"legal_ref": "Art. 74 c. 7-8 DPR 633/72" },
...
]Architecture
mcp-fattura-elettronica-it (this package — standalone MCP server)
├── ItalyPartyValidator(BasePartyValidator) ← Partita IVA modulo-10
├── FatturaGenerator(BaseDocumentGenerator) ← FatturaPA XML v1.6.1
├── FatturaValidator(BaseDocumentValidator) ← lxml XSD v1.6.1
└── FatturaParser(BaseDocumentParser) ← lxml xpath
↑ extends
mcp-einvoicing-core (shared foundation, installed as dependency)
├── BaseDocumentGenerator / Validator / Parser / PartyValidator
├── InvoiceDocument, InvoiceParty, InvoiceLineItem … (Pydantic)
├── xml_utils, logging_utils, exceptions
└── EInvoicingMCPServer (optional multi-country aggregator)📚 Reference Standards
Resource | Link |
FatturaPA Specifications | |
Official XSD v1.6.1 | |
XML Namespace |
|
SDI — Sistema di Interscambio | |
Withholding tax | Art. 25 DPR 600/73 — Modello 770 |
🧪 Tests
# Installare le dipendenze di sviluppo
pip install -e ".[dev]"
# Eseguire tutti i test
pytest tests/ -v
# Eseguire solo i test di integrazione MCP
pytest tests/test_mcp_integration.py -vRoadmap
Version | Features |
v0.1.0 (current) | XML generation, XSD validation, parsing, 21 MCP tools, withholding tax |
v0.2 | Digital signature CAdES-BES and XAdES (smart card, HSM, P12) |
v0.3 | Direct SDI integration via SDICoop SOAP and SFTP — sending and receiving |
v0.4 | Simplified Invoice (TD07/TD08/TD09) — amounts ≤ 400 EUR |
v0.5 | Compliant archiving — integration with AgID accredited providers |
Other e-invoicing MCP servers
Country | Server |
🌍 Global | |
🇧🇪 Belgium | |
🇫🇷 France | |
🇮🇹 Italy |
📄 License
This project is distributed under the Apache 2.0 license. See the LICENSE file for full details.
Copyright 2026 cmendezs
Project maintained by cmendezs. For questions regarding the implementation of the FatturaPA standard, please open an Issue.
Available Tools
43 toolsadd_allegatoAdd AllegatoA
Build an Allegati (attachment) entry to include in a FatturaPA document.
Use this when you need to attach supporting documents (e.g. DDT, contract, PDF) to the invoice. Call once per file, collect results in a list, and pass it to generate_fattura_xml() as the allegati parameter.
attachment_base64 must be valid standard base64 (RFC 4648); the tool verifies decodability. nome_allegato must include the file extension (e.g. 'contract.pdf'). formato_allegato (e.g. 'PDF', 'XML', 'ZIP') is optional but recommended for recipients to identify the content without decoding.
On success returns {'Allegati': {'NomeAllegato', 'Attachment', 'size_bytes', ...}}. On failure returns {'error': ''} (invalid base64 or name > 60 chars).
Inputs: nome_allegato (required), attachment_base64 (required), formato_allegato, descrizione_allegato. Returns: object
add_linea_dettaglioAdd Linea DettaglioA
Build a single DettaglioLinee (line item) entry for the FatturaElettronicaBody.
Use this as step 7 in the invoice generation workflow — call once per line item after build_dati_generali(). Collect all returned dicts into a list and pass it to compute_totali() (step 8) and then generate_fattura_xml() (step 10).
numero_linea must be sequential starting at 1; do not reuse numbers in the same invoice. prezzo_totale must be provided explicitly (not computed); use negative values for credit notes. When aliquota_iva is 0.0, natura is required — call get_natura_codes() to select the code. Set ritenuta='SI' on lines subject to withholding tax and include the DatiRitenuta block from check_ritenuta_acconto() when generating XML. altri_dati_gestionali (optional): structured management data entries, emitted after Natura in the XSD element order. See build_sport_worker_exemption_dato_gestionale() for the codifica introduced by Specifiche Tecniche 1.9.1.
On success returns {'DettaglioLinee': {...}}, plus 'warnings' (list[str]) when aliquota_iva is a non-standard IT VAT rate (outside 4, 5, 10, 22). On failure returns {'error': ''}.
Inputs: descrizione (required), numero_linea (required), natura, quantita, +6 more. Returns: object
build_dati_generaliBuild Dati GeneraliA
Build the DatiGenerali block required in every FatturaElettronicaBody.
Use this as step 6 in the invoice generation workflow, after validate_cessionario() and before add_linea_dettaglio(). Call get_tipo_documento_codes() first to select the correct TD code (most invoices use TD01; credit notes use TD04; professional fee invoices use TD06).
For credit notes (TD04) or debit notes (TD05), set id_documento_riferimento to the original invoice number and data_documento_riferimento to its issue date.
Validates: tipo_documento must be a valid TD01–TD28 code; data must be YYYY-MM-DD; numero must not exceed 20 characters.
On success returns {'DatiGenerali': {...}} ready for generate_fattura_xml(). On failure returns {'error': ''}.
Inputs: data (required), numero (required), tipo_documento (required), divisa, +4 more. Returns: object
build_dati_pagamentoBuild Dati PagamentoA
Build the DatiPagamento block for the FatturaElettronicaBody.
Use this as step 9 in the invoice generation workflow, after compute_totali() and before generate_fattura_xml(). The block is optional in the XML but strongly recommended for B2B invoices.
condizioni_pagamento: TP01 = instalments, TP02 = single full payment, TP03 = advance. modalita_pagamento: MP05 (bank transfer) is most common for B2B; include iban when using MP05. importo_pagamento: for TP02 this should equal totale_fattura from compute_totali(); for TP01 (instalments) call this tool once per instalment tranche.
Validates: condizioni_pagamento in {TP01, TP02, TP03}; modalita_pagamento in MP01–MP23; IBAN format (letters + digits, max 34 chars); data_scadenza_pagamento is YYYY-MM-DD.
On success returns {'DatiPagamento': {...}} ready for generate_fattura_xml(). On failure returns {'error': ''}.
Inputs: importo_pagamento (required), modalita_pagamento (required), condizioni_pagamento (required), iban, +2 more. Returns: object
build_sport_worker_exemption_dato_gestionaleBuild Sport Worker Exemption Dato GestionaleA
Build the AltriDatiGestionali entry for the sport-worker IRPEF exemption codifica.
Covers compensation under art. 36, comma 6, D.Lgs. 36/2021 (lavoro sportivo dilettantistico), exempt from the taxable base up to EUR 15,000/year. Sets TipoDato to 'ESENZSPORT' — verified against AdE Allegato A – Specifiche Tecniche 1.9.1 (in force 2026-05-15). RiferimentoTesto/RiferimentoNumero are not mandated for this codifica (unlike e.g. 'ALI-COMP', which requires RiferimentoNumero); both are left to the caller's discretion here.
Pass the returned dict's 'AltriDatiGestionali' value inside a list to add_linea_dettaglio()'s altri_dati_gestionali parameter — or pass the dict itself if you are constructing the list manually.
On success returns {'AltriDatiGestionali': {'TipoDato': 'ESENZSPORT', ...}}. On failure (invalid riferimento_data) returns {'error': ''}.
Inputs: riferimento_data, riferimento_numero. Returns: object
build_transmission_headerBuild Transmission HeaderA
Build the DatiTrasmissione block required in every FatturaPA header.
Use this as step 3 in the invoice generation workflow, after generate_progressivo_invio() and before validate_cedente_prestatore(). Use lookup_codice_destinatario() first to confirm the recipient code format.
Validates: formato_trasmissione must be 'FPA12' or 'FPR12'; progressivo_invio must be 1–10 alphanumeric characters; pec_destinatario is required when codice_destinatario is '0000000'.
On success returns {'DatiTrasmissione': {...}} ready to pass to generate_fattura_xml(). On failure returns {'error': ''} — do not proceed to XML generation.
Inputs: id_paese (required), id_codice (required), progressivo_invio (required), codice_destinatario (required), +2 more. Returns: object
check_ritenuta_accontoCheck Ritenuta AccontoA
Compute ritenuta d'acconto (withholding tax) for professional invoices.
Use this when issuing professional service invoices (TD01 or TD06) that are subject to withholding tax — typically for self-employed professionals, agents, or freelancers. Also mark the relevant line items with ritenuta='SI' in add_linea_dettaglio(), and pass the returned 'DatiRitenuta' dict to generate_fattura_xml() as dati_ritenuta.
tipo_ritenuta determines the rate: RT01/RT02 = 20% (ritenuta d'acconto, statutory default). RT03 (INPS), RT04 (ENASARCO), RT05 (ENPAM), RT06 (other) have variable rates: aliquota_override or importo_override is required for all of them. causale_pagamento: income category code for Mod. 770 (e.g. 'A' professional fees, 'O' occasional). aliquota_override: supply the actual rate (%) for RT03-RT06, or to override the 20% default for RT01/RT02. importo_override: supply the exact withholding amount when rate-based computation is imprecise.
Validates: tipo_ritenuta must be in RT01-RT06. RT03-RT06 require aliquota_override or importo_override.
On success returns {'DatiRitenuta': {...}, 'importo_ritenuta': str, 'aliquota_applicata': str, 'imponibile_ritenuta': str, 'description': str, 'legal_ref': str}. On failure returns {'error': ''}.
Inputs: imponibile (required), tipo_ritenuta (required), causale_pagamento (required), importo_override, +1 more. Returns: object
compute_totaliCompute TotaliA
Compute DatiRiepilogo VAT summary totals grouped by AliquotaIVA and Natura.
Use this as step 8 in the invoice generation workflow, after all add_linea_dettaglio() calls and before generate_fattura_xml(). Pass the raw line values (not the DettaglioLinee dicts): each item needs 'prezzo_totale' (float), 'aliquota_iva' (float), and optionally 'natura' (str).
Groups lines by (aliquota_iva, natura) pair, sums imponibile, and computes imposta = imponibile × aliquota / 100 (rounded HALF_UP to 2 decimal places). EsigibilitaIVA defaults to 'I' (immediata) for all groups.
Always succeeds (empty list produces empty DatiRiepilogo). Returns: {'DatiRiepilogo': [...], 'totale_imponibile': str, 'totale_imposta': str, 'totale_fattura': str}. Pass 'DatiRiepilogo' directly to generate_fattura_xml() as dati_riepilogo.
Inputs: linee (required). Returns: object
export_to_jsonExport To JsonA
Serialize a parsed FatturaPA dict to a clean, indented JSON string.
Call this after parse_fattura_xml() when you need a human-readable or machine-transferable representation of the invoice. By default, null/empty fields are omitted (include_empty=False) to reduce noise in the output.
indent controls JSON indentation (0 = compact, 2 = standard readable, 4 = wide). include_empty=True retains all keys even when their value is null or empty string.
Always succeeds. Returns {'json_string': str, 'size_chars': int}.
Inputs: parsed_fattura (required), indent, include_empty. Returns: object
generate_cii_invoiceGenerate Cii InvoiceA
Generate a CII CrossIndustryInvoice XML document from an ItalianInvoice dict.
Use this when a CII (UN/CEFACT) wire format is required — for example, for Factur-X embedded XML or ZUGFeRD-compatible output. This tool does NOT produce FatturaPA XML; use generate_fattura_xml() for SdI submission.
Italian national fields are accepted but not emitted (same policy as generate_ubl_invoice).
On success returns {'xml': str, 'length_bytes': int, 'format': 'CII-D16B'}. On validation error returns {'error': str, 'details': list[str]}. On unexpected error returns {'error': str}.
Inputs: invoice_data (required). Returns: object
generate_fattura_semplificataGenerate Fattura SemplificataA
Assemble a complete FatturaSemplificata VFSM10 XML document.
Use this for simplified invoices (TD07), simplified credit notes (TD08), and simplified debit notes (TD09) per art. 21-bis DPR 633/72. These are valid for transactions up to EUR 400 (tax-inclusive).
The simplified format has a flatter structure than the ordinary FatturaPA: no per-line VAT breakdown (DettaglioLinee/DatiRiepilogo), no DatiPagamento in the body. Each DatiBeniServizi entry carries its own Descrizione, Importo, and DatiIVA.
On success returns {'xml': str, 'filename': str, 'length_bytes': int}. On error returns {'error': ''}.
Inputs: dati_generali (required), dati_beni_servizi (required), dati_trasmissione (required), cedente_prestatore (required), +2 m… Returns: object
generate_fattura_xmlGenerate Fattura XmlA
Assemble a complete FatturaPA v1.2.3 XML document from all prepared blocks.
Use this as step 10 in the invoice generation workflow — the final assembly step. All required blocks must come from their respective builder/validator tools; pass the full dict returned by each tool (the function unwraps the top-level key).
Required: dati_trasmissione, cedente_prestatore, cessionario_committente, dati_generali, dettaglio_linee (list), dati_riepilogo (list from compute_totali()). Optional: dati_pagamento, allegati (list), dati_ritenuta.
Does NOT validate against the XSD schema — call validate_fattura_xsd() (step 11) on the returned 'xml' string immediately after to confirm conformance.
On success returns {'xml': str, 'filename': str, 'formato_trasmissione': str, 'length_bytes': int}. On unexpected error returns {'error': ''}.
Inputs: dati_generali (required), dati_riepilogo (required), dettaglio_linee (required), dati_trasmissione (required), +6 more. Returns: object
generate_progressivo_invioGenerate Progressivo InvioA
Generate a ProgressivoInvio identifier for the DatiTrasmissione block.
Use this as step 2 in the invoice generation workflow, before build_transmission_header(). The SDI requires each ProgressivoInvio to be unique per transmitter Partita IVA — in production, pass an explicit monotonically increasing sequence number; use the random default only for testing.
prefix (optional): alphabetic 1–3 char prefix, e.g. 'INV' → 'INV00001'. sequence (optional): integer 1–9999999; random 5-digit value if omitted. Total length must not exceed 10 characters.
On success returns {'progressivo_invio': str, 'length': int}. On failure (invalid prefix) returns {'error': ''}.
Inputs: prefix, sequence. Returns: object
generate_ubl_invoiceGenerate Ubl InvoiceA
Generate a UBL 2.1 Invoice XML document from an ItalianInvoice dict.
Use this for cross-border B2B invoices or Peppol-routed documents. This tool does NOT produce FatturaPA XML; use generate_fattura_xml() for SdI submission.
Italian national fields (progressivo_invio, codice_destinatario, regime_fiscale) are accepted in the input dict but are not emitted in the UBL output — they belong in the FatturaPA DatiTrasmissione header.
profile (BT-24) should be the Peppol BIS Billing 3.0 customisation ID ('urn:cen.eu:en16931:2017#compliant#urn:fdc:peppol.eu:2017:poacc:billing:3.0') or the EN 16931 core profile ('urn:cen.eu:en16931:2017') for non-Peppol use. [Inference: FatturaPA-specific CIUS URN not yet standardised for UBL; verify with AdE if UBL submission to an IT-specific platform is intended.]
On success returns {'xml': str, 'length_bytes': int, 'format': 'UBL-2.1'}. On validation error returns {'error': str, 'details': list[str]}. On unexpected error returns {'error': str}.
Inputs: invoice_data (required). Returns: object
get_natura_codesGet Natura CodesA
Return the complete list of valid Natura exemption codes with legal references.
Call this when add_linea_dettaglio() requires a Natura code (i.e. aliquota_iva is 0.0). Common codes: N1 (excluded, art. 15), N2.1 (out-of-scope, territoriality), N3.1 (exports), N3.2 (intra-EU supplies), N4 (VAT-exempt), N6.x (reverse charge), N7 (OSS/IOSS — VAT paid in another EU state). Note: parent codes N2, N3, N6 were removed from the FatturaPA XSD enumeration effective 1 January 2021. Use sub-codes (N2.1, N2.2, N3.1–N3.6, N6.1–N6.9) instead.
Always succeeds. Returns {'codes': [{'code', 'description', 'legal_ref'}, ...], 'total': int}.
Inputs: no named parameters. Returns: object
get_regime_fiscale_codesGet Regime Fiscale CodesA
Return the complete list of RegimeFiscale codes (RF01–RF19) with descriptions.
Call this to look up the correct fiscal regime code before calling validate_cedente_prestatore(). Every Italian seller must declare a regime: RF01 (ordinary) covers most companies; RF19 (forfettario) covers flat-rate sole traders; all other codes cover specialised VAT regimes.
Always succeeds. Returns {'codes': [{'code': str, 'description': str}, ...], 'total': int}.
Inputs: no named parameters. Returns: object
get_sdi_filenameGet Sdi FilenameA
Generate the canonical SDI filename for a FatturaPA document.
Use this when you need the official filename independently of generate_fattura_xml() (which also produces the filename). The SDI specification requires the format: IT{PartitaIVA}_{ProgressivoInvio}.xml, e.g. IT01234567890_00001.xml.
Validates: partita_iva_cedente must be exactly 11 digits; progressivo_invio must be 1–10 alphanumeric characters. Purely numeric progressivo shorter than 5 digits is zero-padded to 5 digits (e.g. '1' → '00001').
On success returns {'filename': str, 'partita_iva': str, 'progressivo_invio': str, 'length': int}. On failure returns {'error': ''}.
Inputs: progressivo_invio (required), partita_iva_cedente (required). Returns: object
get_tipo_documento_codesGet Tipo Documento CodesA
Return the complete list of document type codes (TD01–TD28) with descriptions and use cases.
Call this to choose the correct TipoDocumento before calling build_dati_generali(). Common codes: TD01 (standard invoice), TD04 (credit note), TD05 (debit note), TD06 (professional fee), TD16–TD19 (reverse charge self-invoices), TD28 (San Marino).
Always succeeds. Returns {'codes': [{'code', 'description', 'use_case'}, ...], 'total': int}.
Inputs: no named parameters. Returns: object
it__archive_invoiceIt Archive InvoiceA
Archive a signed invoice for conservazione sostitutiva. Stores the document with SHA-256 hash, timestamp, and retention metadata per AgID circolare 65/2014. Returns the archive metadata including document_id and retention_until date.
Inputs: document_base64 (required), format_id, signer_id, document_id. Returns: object
it__build_pacchetto_versamentoIt Build Pacchetto VersamentoA
Build a Pacchetto di Versamento (PdV) ZIP archive containing one or more signed invoices and an XML index (IPdV). The PdV is the unit of transfer to an AgID-accredited conservazione provider.
Inputs: documents_json (required), producer_id. Returns: object
it__check_sdi_statusIt Check Sdi StatusA
Check the status of a previously submitted invoice by its IdentificativoSDI. SDI communicates status asynchronously via notifications; this returns the last known local status.
Inputs: identificativo_sdi (required). Returns: object
it__get_sdi_channel_infoIt Get Sdi Channel InfoA
Show current SDI channel configuration: environment, channel type, channel ID, endpoint URL, and certificate status. Does not expose sensitive values (cert_password).
Inputs: no named parameters. Returns: object
it__list_archived_invoicesIt List Archived InvoicesA
List all archived invoices. Returns a list of archive metadata records sorted by archive date.
Inputs: no named parameters. Returns: object
it__parse_sdi_notificationIt Parse Sdi NotificationA
Parse an SDI notification XML into a structured dict. Supports all notification types: RC (delivery receipt), NS (rejection with error codes), MC (delivery failure), NE (seller outcome), EC (buyer acceptance/rejection), SE (outcome rejection), DT (deadline expiry), MT (metadata), AT (undeliverable attestation).
Inputs: notification_xml (required). Returns: object
it__retrieve_archived_invoiceIt Retrieve Archived InvoiceA
Retrieve an archived invoice by its document_id. Returns the document content (base64-encoded) and its archive metadata.
Inputs: document_id (required). Returns: object
it__send_esito_committenteIt Send Esito CommittenteA
Send an acceptance (EC01) or rejection (EC02) notification to SDI for a received invoice. The esito XML must conform to the NotificaEsitoCommittente schema (MessaggiTypes_v1.1.xsd). Requires confirmation (irreversible).
Inputs: esito (required), esito_xml (required), nome_file (required), identificativo_sdi (required), +1 more. Returns: object
it__sign_fattura_cadesIt Sign Fattura CadesA
Apply a CAdES-BES (CMS/PKCS#7) attached signature to a FatturaPA XML document. The output is a DER-encoded .xml.p7m file (base64-encoded in the response). Requires a qualified PKCS#12 certificate. Uses the signer microservice when available, falls back to direct signing. Requires confirmation (irreversible).
Inputs: xml (required), cert_path, cert_password, confirmation_token. Returns: object
it__sign_fattura_xadesIt Sign Fattura XadesA
Apply an XAdES-BES enveloped XML signature to a FatturaPA XML document. The signed XML retains the .xml extension. Requires a qualified PKCS#12 certificate. Uses the signer microservice when available, falls back to direct signing. Requires confirmation (irreversible).
Inputs: xml (required), cert_path, cert_password, confirmation_token. Returns: object
it__submit_to_sdiIt Submit To SdiA
Submit a signed FatturaPA invoice to SDI via SDICoop. The invoice must be signed (XAdES-BES or CAdES-BES) before submission. Requires mTLS certificate configuration. Returns the IdentificativoSDI assigned by SDI. Requires confirmation (irreversible).
Inputs: filename (required), signed_file_base64 (required), confirmation_token. Returns: object
it__verify_archive_integrityIt Verify Archive IntegrityA
Verify the integrity of an archived document by recomputing its SHA-256 hash and comparing against the stored hash.
Inputs: document_id (required). Returns: object
lookup_codice_destinatarioLookup Codice DestinatarioA
Validate the format of a CodiceDestinatario (SDI recipient code) or PEC address.
Call this before build_transmission_header() to confirm the recipient routing type and that the code or PEC address is correctly formatted. At least one of codice or pec must be provided.
Routing rules:
codice is 6 alphanumeric chars (e.g. 'A1B2C3') → routing_type: 'SDI_CODE' (PA/IPA, FPA12)
codice is 7 alphanumeric chars (e.g. 'X1Y2Z3W') → routing_type: 'SDI_CODE' (B2B intermediary, FPR12)
codice is '0000000' (7 zeros) → routing_type: 'PEC'; pec_destinatario is then mandatory in build_transmission_header()
pec only (no codice) → validates email format, routing_type: 'PEC'
IPA note: 6-char = IPA code (PA), 7-char = B2B intermediary code (FPR12 routing). PA office codes can be looked up at https://www.indicepa.gov.it. This tool performs format validation only, no live query against the SDI SOAP directory service or the IPA registry (planned for a future release).
Per-channel cap (reference only, not enforced here — this tool validates the format of a single code, not channel-wide allocation): per AdE Specifiche Tecniche 1.9.1 (in force 2026-05-15), an accredited reception channel (WS or SFTP) may request a maximum of 300 CodiceDestinatario codes via the Sistema di Accreditamento once it has passed to production. This cap is unrelated to, and does not change, the per-invoice 6/7-character format validated above.
On success returns a dict with 'routing_type', 'codice_destinatario' and/or 'pec_destinatario', and a 'note' with usage guidance. On invalid input returns {'error': ''}.
Inputs: pec, codice. Returns: object
parse_cii_invoiceParse Cii InvoiceA
Parse a CII CrossIndustryInvoice XML string into an EN 16931 structured dict.
Extracts the EN 16931 core field set. Italian national fields are returned with their ItalianInvoice defaults since CII does not carry them.
Use this to inspect Factur-X / ZUGFeRD invoices, or to round-trip the output of generate_cii_invoice() for verification.
On success returns the ItalianInvoice fields as a JSON-serialisable dict. On failure returns {'error': str}.
Inputs: xml_string (required). Returns: object
parse_fattura_semplificata_xmlParse Fattura Semplificata XmlA
Parse a FatturaSemplificata XML string into a structured Python dict.
Use this to inspect simplified invoices (TD07/TD08/TD09) received from counterparties or to verify output of generate_fattura_semplificata().
Extracts: versione, transmission data, seller identity and address, buyer fiscal identifiers and optional address, document type/date/number, all DatiBeniServizi entries, and DatiFatturaRettificata if present.
On success returns {'versione': str, 'header': {...}, 'body': {...}}. On error returns {'error': ''}.
Inputs: xml_string (required). Returns: object
parse_fattura_xmlParse Fattura XmlA
Parse a FatturaPA XML string into a structured Python dict.
Use this to inspect or process invoices received from counterparties, or to verify the output of generate_fattura_xml(). Accepts both FPR12 (B2B) and FPA12 (PA) formats. The result can be passed directly to export_to_json().
Extracts: versione, transmission data, seller/buyer identity and address, document type/date/number/causale, all DettaglioLinee, DatiRiepilogo, and DatiPagamento if present. Fields not found in the XML are returned as null.
On success returns {'versione': str, 'header': {...}, 'body': {...}}. On XML parse error returns {'error': 'XML parse error: '}. On missing lxml returns {'error': 'lxml is not installed...'}.
Inputs: xml_string (required). Returns: object
parse_ubl_invoiceParse Ubl InvoiceA
Parse a UBL 2.1 invoice XML string into an EN 16931 structured dict.
Extracts the EN 16931 core field set. Italian national fields (progressivo_invio, regime_fiscale, etc.) are returned with their ItalianInvoice defaults since UBL 2.1 does not carry them.
Use this to inspect cross-border invoices received in UBL format, or to round-trip the output of generate_ubl_invoice() for verification.
On success returns the ItalianInvoice fields as a JSON-serialisable dict. On failure returns {'error': str}.
Inputs: xml_string (required). Returns: object
validate_cedente_prestatoreValidate Cedente PrestatoreA
Validate and build the CedentePrestatore (seller) block for FatturaPA.
Use this as step 4 in the invoice generation workflow, after build_transmission_header() and before validate_cessionario(). Call get_regime_fiscale_codes() first if you need to look up the RF code.
Gruppo IVA (VAT-group) sellers: when id_codice is a VAT-group IdFiscaleIVA, pass codice_fiscale set to the Codice Fiscale of the specific participating member company issuing this invoice, never the group's own CF. This mirrors the buyer-side rule enforced by SdI scarto code 00327 (see mcp_fattura_elettronica_it.sdi.notifications.SCARTO_CODE_REFERENCE); SdI does not publish an equivalent seller-side control code, but the same distinction applies structurally.
Validates: either denominazione or both nome+cognome must be provided (mutually exclusive); regime_fiscale must be a valid RF01–RF19 code; Italian Partita IVA (id_paese='IT') must be exactly 11 digits; codice_fiscale, if provided, must be 16 alphanumeric characters (individuals) or 11 digits (companies/VAT groups).
On success returns {'CedentePrestatore': {...}} ready to pass to generate_fattura_xml(). On failure returns {'error': ''} listing all validation issues joined by '; '.
Inputs: id_paese (required), id_codice (required), cap, nome, +7 more. Returns: object
validate_cessionarioValidate CessionarioA
Validate and build the CessionarioCommittente (buyer) block for FatturaPA.
Use this as step 5 in the invoice generation workflow, after validate_cedente_prestatore() and before build_dati_generali().
Validates: either denominazione or both nome+cognome must be provided (mutually exclusive); at least one tax identifier (id_codice with id_paese, or codice_fiscale) is required; id_codice requires id_paese to be set.
Italian B2C buyers with only a CodiceFiscale: set codice_fiscale and leave id_paese/id_codice empty. Foreign B2B buyers: set id_paese + id_codice. For B2G invoices (FPA12): routing to the Public Administration is via a 6-char IPA office CodiceDestinatario in build_transmission_header(), not via this tool — look up the code at https://www.indicepa.gov.it.
Gruppo IVA (VAT-group) buyers: when id_paese/id_codice are omitted and codice_fiscale is an 11-digit (company-format) code, this may be a VAT-group's own CF rather than a participating member's. SdI rejects that combination with scarto code 00327 (see mcp_fattura_elettronica_it.sdi.notifications. SCARTO_CODE_REFERENCE) — this tool cannot validate VAT-group membership offline, so it only warns on the detectable structural precondition (IdFiscaleIVA absent
11-digit codice_fiscale); the returned 'warnings' list flags this case. Confirm codice_fiscale identifies the specific member company, not the group itself.
On success returns {'CessionarioCommittente': {...}} ready for generate_fattura_xml(), plus 'warnings' (list[str]) when the 00327 structural precondition is detected. On failure returns {'error': ''} listing all issues joined by '; '.
Inputs: cap, nome, comune, cognome, +6 more. Returns: object
validate_cii_invoiceValidate Cii InvoiceA
Validate a CII CrossIndustryInvoice XML string for structural correctness.
Performs structural validation by parsing the XML into an EN16931Invoice and checking that required core fields are present and non-empty.
Note: this tool does NOT validate against the normative CII D16B XSD schema. For full schema validation use a dedicated CII or ZUGFeRD validator.
On success returns {'valid': true, 'warnings': list[str]}. On failure returns {'valid': false, 'errors': list[str]}. On parse error returns {'valid': false, 'errors': ['XML parse error: ...']}.
Inputs: xml_string (required). Returns: object
validate_fattura_semplificata_xsdValidate Fattura Semplificata XsdA
Validate a FatturaSemplificata XML string against the VFSM10 XSD v1.0.2.
Call this immediately after generate_fattura_semplificata() to confirm XSD conformance. Also use to verify third-party simplified invoices.
Requires lxml. Validates namespace, element structure, data types, and cardinality.
On success returns {'valid': true, 'errors': []}. On failure returns {'valid': false, 'errors': ['...']}. On setup error returns {'error': ''}.
Inputs: xml_string (required). Returns: object
validate_fattura_xsdValidate Fattura XsdA
Validate a FatturaPA XML string against the official Agenzia delle Entrate XSD v1.2.3.
Use this as step 11 — always call immediately after generate_fattura_xml() before storing or transmitting the document. Also use to verify third-party invoices received from suppliers.
Automatically selects the correct XSD based on the document's versione attribute:
FPR12 (B2B/B2C) uses FatturaPA_FPR12_v1.2.3.xsd; FPA12 (B2G) uses
FatturaPA_FPA12_v1.2.3.xsd. FATTURA_XSD_PATH env var overrides both.
Requires lxml. Validates namespace, element structure, data types, and cardinality.
On success returns {'valid': true, 'formato_trasmissione': 'FPR12'|'FPA12', 'errors': []}. On failure returns {'valid': false, 'errors': ['', ...]}. On setup error (missing lxml or XSD file) returns {'error': ''}.
Inputs: xml_string (required). Returns: object
validate_partita_ivaValidate Partita IvaA
Validate an Italian Partita IVA for format (11 digits) and modulo-10 checksum.
Call this as an early sanity check on the seller's VAT number before passing it to validate_cedente_prestatore(). Strips whitespace before validation.
Applies the official Agenzia delle Entrate control algorithm: odd-position digits are taken as-is; even-position digits are doubled (subtract 9 if > 9); the last digit must equal (10 - sum % 10) % 10.
On success returns {'valid': true, 'value': '<cleaned_piva>'}. On failure returns {'valid': false, 'value': '', 'error': ''}.
Inputs: partita_iva (required). Returns: object
validate_partita_iva_formatValidate Partita Iva FormatA
Validate an Italian Partita IVA for format (11 digits) and modulo-10 checksum.
Use this as step 1 in the invoice generation workflow before any other tool. Equivalent to validate_partita_iva() in header tools — use this standalone version when you only need the validation result without importing header tools.
Strips whitespace, checks for exactly 11 digits, then applies the official Agenzia delle Entrate control algorithm to verify the check digit.
On success returns {'valid': true, 'value': '<cleaned_piva>'}. On failure returns {'valid': false, 'value': '', 'error': ''}.
Inputs: partita_iva (required). Returns: object
validate_ubl_invoiceValidate Ubl InvoiceA
Validate a UBL 2.1 invoice XML string for structural correctness.
Performs structural validation by parsing the XML into an EN16931Invoice and checking that required core fields (invoice_number, invoice_date, seller, buyer, at least one line item) are present and non-empty.
Note: this tool does NOT validate against the normative UBL 2.1 XSD schema (the UBL XSD files are not bundled with this package). For full XSD validation use a dedicated UBL validator or the Peppol Validator tool.
On success returns {'valid': true, 'warnings': list[str]}. On failure returns {'valid': false, 'errors': list[str]}. On parse error returns {'valid': false, 'errors': ['XML parse error: ...']}.
Inputs: xml_string (required). Returns: object
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 43 tools
Tools are mostly distinct, each targeting a specific invoice-building step or format. The only clear duplication is validate_partita_iva and validate_partita_iva_format, which are explicitly equivalent and could cause misselection. Other overlaps (e.g., generate_fattura_xml vs generate_fattura_semplificata) are well-differentiated by output format.
Names follow a consistent verb_noun pattern (build_, generate_, validate_, parse_, get_, etc.) with snake_case throughout. Minor deviations: the it__ prefix for SDI/archiving operations and slight verb variation (lookup vs get, compute vs build) but no mixing of conventions or camelCase.
At 43 tools, this is far beyond the typical 3-15 range. While the FatturaPA domain is complex and covers generation, validation, conversion, signing, submission, and archiving, the sheer number feels excessive and may overwhelm agents. It is not an extreme mismatch (50+), but it is still too many for most practical uses.
The tool surface is remarkably complete: it covers the full invoice lifecycle—building blocks (seller, buyer, transmission, line items, totals), multiple output formats (FatturaPA, simplified, UBL, CII), validation (XSD, structural), parsing, signing, SDI submission/status/notification handling, and archiving with retrieval and integrity checks. No obvious gaps exist for the domain.
Maintenance
Related MCP Connectors
Official Openapi® MCP server: Italian company data, PEC, SMS, vehicles, geocoding and more APIs.
Model Context Protocol server for the Apideck Unified API. Connect any MCP-compatible agent framework to 100+ accounting systems, HRIS platforms, file storage providers, and more through one integration. More information https://www.apideck.com/mcp-server
MCP server for Codat — companies, connections, invoices, bills and financial statements.
MCP server for the PDFGate API. Generate PDFs, manage documents and handle e-signatures.
Related MCP Servers
- AlicenseAqualityBmaintenanceModel Context Protocol (MCP) server for French Electronic Invoicing (NF XP Z12-013). Provide tools to validate, generate, and explore API specifications for PDP/OD interoperability.34Apache 2.0
- AlicenseAqualityBmaintenanceModel Context Protocol (MCP) server for Polish Electronic Invoicing (KSeF / FA(2)). Provides tools to validate, generate, and explore API specifications for KSeF interoperability.10263 PyPI3Apache 2.0
- AlicenseAqualityBmaintenanceModel Context Protocol (MCP) server for Spanish Electronic Invoicing. Provides tools to generate, validate, and submit invoices across VERI\*FACTU, Facturae/FACe, SII, TicketBAI, and Crea y Crece B2B.20169 PyPI3Apache 2.0
- AlicenseAqualityBmaintenanceModel Context Protocol (MCP) server for Singapore Electronic Invoicing (InvoiceNow / PINT-SG / Peppol 5-Corner Model). Provides tools to validate, generate, and explore API specifications for IRAS / Peppol interoperability.1755 PyPIApache 2.0