mcp-fattura-elettronica-it 🇮🇹

Server MCP Python per la fatturazione elettronica italiana in formato FatturaPA XML (standard SDI / Agenzia delle Entrate, versione 1.6.1). Permette agli agenti IA (Claude, IDE) di generare, validare e analizzare fatture elettroniche B2B, B2G e transfrontaliere direttamente conformi alle specifiche tecniche del 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.

🚀 Installazione

Via PyPI (raccomandato)

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.

Senza installazione previa con uvx:

uvx mcp-fattura-elettronica-it

Dalle sorgenti

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

⚙️ Configurazione

Il server non richiede credenziali esterne in v0.1.0. Le variabili d'ambiente disponibili sono:

🤖 Integrazione Claude Desktop

Aggiungere al file claude_desktop_config.json:

{
  "mcpServers": {
    "fattura-elettronica-it": {
      "command": "uvx",
      "args": ["mcp-fattura-elettronica-it"]
    }
  }
}

⌨️ Integrazione Cursor

File di configurazione (~/.cursor/mcp.json oppure .cursor/mcp.json nella cartella del progetto):

{
  "mcpServers": {
    "fattura-elettronica-it": {
      "command": "uvx",
      "args": ["mcp-fattura-elettronica-it"]
    }
  }
}

🪐 Integrazione Kiro

{
  "mcpServers": {
    "fattura-elettronica-it": {
      "command": "uvx",
      "args": ["mcp-fattura-elettronica-it"],
      "disabled": false,
      "autoApprove": []
    }
  }
}

🧰 Strumenti MCP disponibili

Header — FatturaElettronicaHeader (7 strumenti)

Body — FatturaElettronicaBody (7 strumenti)

Globali — generazione e validazione (7 strumenti)

Esempi di utilizzo

Esempio 1 — Generare una fattura B2B completa

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 }

Esempio 2 — Fattura professionale con 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"
  }

Esempio 3 — Consultare i codici di esenzione IVA

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)

📚 Standard di riferimento

🧪 Test

# 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

Other e-invoicing MCP servers

📄 Licenza

Questo progetto è distribuito sotto licenza Apache 2.0.
Vedere il file LICENSE per i dettagli completi.

Copyright 2026 cmendezs

Progetto mantenuto da cmendezs. Per domande relative all'implementazione dello standard FatturaPA, aprire una Issue.