Skip to main content
Glama
mcp-fattura-elettronica-it

mcp-fattura-elettronica-it

mcp-fattura-elettronica-it 🇮🇹

License PyPI version Python mcp-fattura-elettronica-it MCP server

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

pip install mcp-fattura-elettronica-it

mcp-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-it

From 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

Log level (DEBUG, INFO, WARNING, ERROR)

INFO

FATTURA_XSD_PATH

Path to the FatturaPA XSD file

schemas/FatturaPA_v1.6.1.xsd

🤖 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_transmission_header

Build DatiTrasmissione block: ProgressivoInvio, CodiceDestinatario, PECDestinatario

validate_cedente_prestatore

Validate seller block: IdFiscaleIVA, Anagrafica, Sede, RegimeFiscale codes

validate_cessionario

Validate buyer block: IdFiscaleIVA or CodiceFiscale, Sede

get_regime_fiscale_codes

Return all valid RegimeFiscale codes with descriptions (RF01–RF19)

validate_partita_iva

Validate Italian VAT number (Partita IVA) format and checksum (11 digits)

generate_progressivo_invio

Generate a unique ProgressivoInvio identifier (max 10 alphanumeric chars)

lookup_codice_destinatario

Return info about a CodiceDestinatario (6-char SDI code) or PEC address

Body — FatturaElettronicaBody (7 tools)

Tool

Description

build_dati_generali

Build DatiGenerali block: TipoDocumento, Divisa, Data, Numero, Causale

get_tipo_documento_codes

Return all TD01–TD28 codes with descriptions and use cases (incl. cross-border)

add_linea_dettaglio

Add a DettaglioLinee entry: NumeroLinea, Descrizione, Quantita, PrezzoUnitario

compute_totali

Compute DatiRiepilogo: imponibile, imposta, AliquotaIVA from line items

get_natura_codes

Return all Natura codes (N1–N7 and sub-codes) for VAT exemption with legal references

build_dati_pagamento

Build DatiPagamento: CondizioniPagamento (TP01/02/03), ModalitaPagamento (MP01–MP23)

add_allegato

Attach a base64-encoded document to the Allegati block with name and format

Global — generation and validation (7 tools)

Tool

Description

generate_fattura_xml

Generate a complete FatturaPA XML file from structured input data

validate_fattura_xsd

Validate a FatturaPA XML string against the official XSD schema v1.6.1

parse_fattura_xml

Parse an existing FatturaPA XML string and return a structured JSON dict

export_to_json

Export a parsed FatturaPA structure to clean JSON format

validate_partita_iva_format

Validate Partita IVA format and Luhn-like checksum (11-digit Italian VAT)

get_sdi_filename

Generate the official SDI filename: IT{PartitaIVA}_{ProgressivoInvio}.xml

check_ritenuta_acconto

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

fatturapa.gov.it

Official XSD v1.6.1

Schema v1.2.2 — Agenzia delle Entrate

XML Namespace

http://ivaservizi.agenziaentrate.gov.it/docs/xsd/fatture/v1.2

SDI — Sistema di Interscambio

Agenzia delle Entrate

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 -v

Roadmap

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

mcp-einvoicing-core

🇧🇪 Belgium

mcp-einvoicing-be

🇫🇷 France

mcp-facture-electronique-fr

🇮🇹 Italy

mcp-fattura-elettronica-it


📄 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 tools
add_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

    A4/5.0

    Scored across 43 tools

    Disambiguation4/5

    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.

    Naming Consistency4/5

    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.

    Tool Count2/5

    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.

    Completeness5/5

    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

    ActivityStale
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      B
      maintenance
      Model 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.
      34
      Apache 2.0
    • A
      license
      A
      quality
      B
      maintenance
      Model Context Protocol (MCP) server for Polish Electronic Invoicing (KSeF / FA(2)). Provides tools to validate, generate, and explore API specifications for KSeF interoperability.
      10
      263 PyPI
      3
      Apache 2.0
    • A
      license
      A
      quality
      B
      maintenance
      Model 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.
      20
      169 PyPI
      3
      Apache 2.0
    • A
      license
      A
      quality
      B
      maintenance
      Model 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.
      17
      55 PyPI
      Apache 2.0