mcp-fattura-elettronica-it 🇮🇹

English | Italiano

A Python MCP server for Italian electronic invoicing in FatturaPA XML format (SDI / Agenzia delle Entrate standard, XSD v1.2.3, Specifiche Tecniche 1.9.1). It enables AI agents (Claude, IDEs) to generate, validate, and analyze B2B, B2G, and cross-border electronic invoices that are directly compliant with the technical specifications of the Sistema di Interscambio (SDI).

Note: "Specifiche Tecniche" (the AdE Allegato A controls/codifiche document) and the XSD schema are two separate artefacts with independent version numbers. Specifiche Tecniche 1.9.1 (in force 2026-05-15) does not change the XSD — the bundled schema remains v1.2.3.

This is a Model Context Protocol (MCP) server exposing 43 tools covering the full lifecycle of a FatturaPA XML document: transmission header construction, seller/buyer validation (including Gruppo IVA / VAT-group CodiceFiscale), document type codes (TD01-TD28), line items with AltriDatiGestionali support, VAT summary computation, payment terms, XSD validation against the official Agenzia delle Entrate schema (v1.2.3), XML generation, parsing, JSON export, SDI filename generation, withholding tax (ritenuta d'acconto) calculation, digital signatures (XAdES-BES and CAdES-BES), direct SDI transmission via SDICoop SOAP, SDI notification parsing, and conservazione sostitutiva (legally compliant archiving per AgID). Licensed under Apache 2.0.

🚀 Installation

Via PyPI (recommended)

pip install mcp-fattura-elettronica-it

mcp-einvoicing-core is installed automatically as a dependency. lxml is also required and included, so no extra steps are 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 available environment variables are:

🤖 Claude Desktop integration

Add the following to your 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)

Body: FatturaElettronicaBody (8 tools)

Global: generation and validation (7 tools)

Simplified invoices: FatturaSemplificata VFSM10 (3 tools)

Simplified invoices (art. 21-bis DPR 633/72) are valid for transactions up to EUR 400 (tax-inclusive). They use a flatter structure than ordinary FatturaPA: no per-line VAT breakdown, no DatiRiepilogo. Each DatiBeniServizi entry carries its own Descrizione, Importo, and DatiIVA. The VFSM10 format uses namespace v1.0 and is separate from the EN 16931 CIUS used by ordinary invoices.

Digital signatures (2 tools)

Both signature formats are accepted by SDI (Specifiche tecniche SDI v1.8.4, section 2.1). Supports dual mode: signer microservice (keeps keys out of the MCP process) or direct PKCS#12 loading. Requires cryptography>=42.0.0 (installed via the [xml-sign] extra on mcp-einvoicing-core).

SDI integration (5 tools)

Requires AdE accreditation for production use. Configure via SDI_CERT_PATH, SDI_CERT_PASSWORD, SDI_ENVIRONMENT (test/production), and SDI_ENDPOINT_URL (override) environment variables.

Conservazione sostitutiva / archiving (5 tools)

Per AgID circolare 65/2014 and DM 17/06/2014, electronic invoices must be archived for a minimum of 10 years. The local filesystem backend is for development only; production requires integration with an AgID-accredited conservazione provider.

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(...all previous blocks...)
    → { "xml": "<?xml ...", "filename": "IT01234567897_00001.xml" }

11. validate_fattura_xsd(xml_string=...)
    → { "valid": true }

Example 2: Professional invoice with withholding tax

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: Look up 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.2.3
├── FatturaValidator(BaseDocumentValidator)   ← lxml XSD v1.2.3
└── 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

🧪 Tests

# Install development dependencies
pip install -e ".[dev]"

# Run all tests
pytest tests/ -v

# Run only MCP integration tests
pytest tests/test_mcp_integration.py -v

Roadmap

Other e-invoicing MCP servers

📄 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 about the FatturaPA standard implementation, please open an Issue.