mcp-fattura-elettronica-it 🇮🇹

English | Italiano

Introduction

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). It is built on mcp-einvoicing-core, the shared base library for e-invoicing MCP servers.

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"],
      "env": {
        "SDI_ENVIRONMENT": "test",
        "SDI_CERT_PATH": "/path/to/your-cert.p12",
        "SDI_CERT_PASSWORD": "your-cert-password",
        "SDI_CHANNEL_ID": "your-channel-id"
      }
    }
  }
}

Cursor integration

Cursor supports MCP servers via stdio. Add the configuration in:

• Global (all projects): ~/.cursor/mcp.json
• Project (this repository only): .cursor/mcp.json

{
  "mcpServers": {
    "fattura-elettronica-it": {
      "command": "uvx",
      "args": ["mcp-fattura-elettronica-it"],
      "env": {
        "SDI_ENVIRONMENT": "test",
        "SDI_CERT_PATH": "/path/to/your-cert.p12",
        "SDI_CERT_PASSWORD": "your-cert-password",
        "SDI_CHANNEL_ID": "your-channel-id"
      }
    }
  }
}

Reload the Cursor window (Ctrl+Shift+P then Reload Window) to apply the changes.

Kiro integration

Kiro supports MCP servers via its dedicated configuration file. Two levels are available:

• Global (all projects): ~/.kiro/settings/mcp.json
• Workspace (this repository only): .kiro/settings/mcp.json

{
  "mcpServers": {
    "fattura-elettronica-it": {
      "command": "uvx",
      "args": ["mcp-fattura-elettronica-it"],
      "env": {
        "SDI_ENVIRONMENT": "test",
        "SDI_CERT_PATH": "/path/to/your-cert.p12",
        "SDI_CERT_PASSWORD": "your-cert-password",
        "SDI_CHANNEL_ID": "your-channel-id"
      },
      "disabled": false,
      "autoApprove": []
    }
  }
}

The file is automatically reloaded on save. You can also open the config via the command palette (Cmd+Shift+P / Ctrl+Shift+P) then MCP.

Kiro security tip: rather than writing secrets in plain text, use the syntax "SDI_CERT_PASSWORD": "${SDI_CERT_PASSWORD}", Kiro resolves shell environment variables at startup.

Available 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)