Fattura Elettronica IT

mcp-fattura-elettronica-it 🇮🇹

English | Italiano

---

简介

一个用于 FatturaPA XML 格式 意大利电子发票 的 Python MCP 服务（符合 SDI / Agenzia delle Entrate 标准，XSD v1.2.3，Specifiche Tecniche 1.9.1）。它使 AI Agent（Claude、IDE）能够生成、验证和分析 B2B、B2G 及跨境电子发票，并确保发票直接符合 Sistema di Interscambio（SDI）的技术规范。该服务基于 mcp-einvoicing-core 构建，这是电子发票 MCP 服务的共享基础库。

注意：“Specifiche Tecniche”（AdE Allegato A 控制项/编码文档）与 XSD 架构是两个独立的制品，各自有独立的版本号。Specifiche Tecniche 1.9.1（自 2026-05-15 起生效）不会更改 XSD — 随附的架构仍为 v1.2.3。

这是一个 Model Context Protocol (MCP) 服务，提供 43 个工具，涵盖 FatturaPA XML 文档的完整生命周期：构建传输头信息、验证卖方/买方（包括 Gruppo IVA / VAT-group CodiceFiscale）、文档类型代码（TD01-TD28）、支持 AltriDatiGestionali 的行项目、计算 VAT 汇总、付款条款、依据 Agenzia delle Entrate 官方架构（v1.2.3）验证 XSD、生成 XML、解析、导出 JSON、生成 SDI 文件名、计算预扣税（ritenuta d'acconto）、数字签名（XAdES-BES 和 CAdES-BES）、通过 SDICoop SOAP 直接向 SDI 传输、解析 SDI 通知，以及 conservazione sostitutiva（符合 AgID 要求的法律合规归档）。采用 Apache 2.0 许可证。

安装

通过 PyPI（推荐）

pip install mcp-fattura-elettronica-it

mcp-einvoicing-core 会作为依赖项自动安装。 同时也会安装所需的 lxml，因此无需额外操作。

无需预先安装，使用 uvx：

uvx mcp-fattura-elettronica-it

从源代码安装

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

配置

可用的环境变量如下：

Variable	Description	Default
LOG_LEVEL	日志级别（DEBUG、INFO、WARNING、ERROR）	INFO
FATTURA_XSD_PATH	FatturaPA XSD 文件的路径	schemas/FatturaPA_v1.2.3.xsd
SDI_ENVIRONMENT	SDI 环境：test 或 production	test
SDI_CERT_PATH	SDI 的 PKCS#12 mTLS 证书路径	（无）
SDI_CERT_PASSWORD	PKCS#12 文件的密码	（无）
SDI_ENDPOINT_URL	SDICoop 端点 URL 覆盖值	（根据环境自动设置）
SDI_CHANNEL_ID	AdE 认证过程中分配的通道 ID	（无）
EINVOICING_SIGNER_SOCKET	签名微服务的 Unix 套接字	（无）
EINVOICING_SIGNER_TOKEN	签名微服务的身份验证令牌	（无）
CONSERVAZIONE_STORAGE_PATH	本地归档存储路径（仅用于开发）	.conservazione/

Claude Desktop 集成

将以下内容添加到 claude_desktop_config.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"
      }
    }
  }
}

Cursor 集成

Cursor 支持通过 stdio 使用 MCP 服务。请在以下位置添加配置：

• 全局（所有项目）：~/.cursor/mcp.json
• 项目（仅此仓库）：.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"
      }
    }
  }
}

重新加载 Cursor 窗口（按 Ctrl+Shift+P，然后选择 Reload Window）以应用更改。

Kiro 集成

Kiro 通过专用配置文件支持 MCP 服务。提供两个级别：

• 全局（所有项目）：~/.kiro/settings/mcp.json
• 工作区（仅此仓库）：.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": []
    }
  }
}

保存后，文件会自动重新加载。你也可以通过命令面板（Cmd+Shift+P / Ctrl+Shift+P）打开配置，然后选择 MCP。

Kiro 安全提示：不要以明文形式写入机密，而应使用 "SDI_CERT_PASSWORD": "${SDI_CERT_PASSWORD}" 语法。Kiro 会在启动时解析 shell 环境变量。

可用工具

抬头：FatturaElettronicaHeader（7 个工具）

工具	描述
build_transmission_header	构建 DatiTrasmissione 块：ProgressivoInvio、CodiceDestinatario、PECDestinatario
validate_cedente_prestatore	验证卖方块：IdFiscaleIVA、可选的 Gruppo IVA 成员 CodiceFiscale、Anagrafica、Sede、RegimeFiscale 代码
validate_cessionario	验证买方块：IdFiscaleIVA 或 CodiceFiscale、Sede（针对 Gruppo IVA 的废弃代码 00327 结构性前提发出警告）
get_regime_fiscale_codes	返回所有有效的 RegimeFiscale 代码及其说明（RF01-RF19）
validate_partita_iva	验证意大利增值税号（Partita IVA）的格式和校验和（11 位数字）
generate_progressivo_invio	生成唯一的 ProgressivoInvio 标识符（最多 10 个字母数字字符）
lookup_codice_destinatario	返回 CodiceDestinatario（6 位 SDI 代码）或 PEC 地址的信息（每个经认证的渠道最多可使用 300 个代码，Specifiche Tecniche 1.9.1）

正文：FatturaElettronicaBody（8 个工具）

工具	描述
build_dati_generali	构建 DatiGenerali 块：TipoDocumento、Divisa、Data、Numero、Causale
get_tipo_documento_codes	返回所有 TD01-TD28 代码及其说明和适用场景（包括跨境场景）
add_linea_dettaglio	添加 DettaglioLinee 条目：NumeroLinea、Descrizione、Quantita、PrezzoUnitario、可选的 AltriDatiGestionali
build_sport_worker_exemption_dato_gestionale	为体育工作者的 IRPEF 免税构建 AltriDatiGestionali 条目（TipoDato='ESENZSPORT'，Specifiche Tecniche 1.9.1）
compute_totali	根据行项目计算 DatiRiepilogo：imponibile、imposta、AliquotaIVA
get_natura_codes	返回所有用于增值税免税的 Natura 代码（N1-N7 及子代码），并附法律依据
build_dati_pagamento	构建 DatiPagamento：CondizioniPagamento（TP01/02/03）、ModalitaPagamento（MP01-MP23）
add_allegato	将经过 base64 编码的文档附加到 Allegati 块，并指定名称和格式

全局：生成与验证（7 个工具）

工具	描述
generate_fattura_xml	根据结构化输入数据生成完整的 FatturaPA XML 文件
validate_fattura_xsd	根据官方 XSD 架构 v1.2.3 验证 FatturaPA XML 字符串
parse_fattura_xml	解析现有的 FatturaPA XML 字符串，并返回结构化 JSON 字典
export_to_json	将解析后的 FatturaPA 结构导出为整洁的 JSON 格式
validate_partita_iva_format	验证 Partita IVA 格式和类似 Luhn 的校验和（11 位意大利增值税号）
get_sdi_filename	生成官方 SDI 文件名：IT{PartitaIVA}_{ProgressivoInvio}.xml
check_ritenuta_acconto	检查并计算专业发票的 ritenuta d'acconto（预扣税）

简化发票：FatturaSemplificata VFSM10（3 个工具）

工具	描述
generate_fattura_semplificata	使用 VFSM10 格式生成简化发票 XML（TD07/TD08/TD09）
validate_fattura_semplificata_xsd	根据 VFSM10 XSD v1.0.2 验证简化发票 XML
parse_fattura_semplificata_xml	将简化发票 XML 解析为结构化字典

简化发票（第 21-bis 条 DPR 633/72）适用于金额不超过 400 欧元（含税）的交易。与普通 FatturaPA 相比，其结构更扁平：没有逐行 VAT 明细，也没有 DatiRiepilogo。每个 DatiBeniServizi 条目都包含自己的 Descrizione、Importo 和 DatiIVA。VFSM10 格式使用命名空间 v1.0，与普通发票使用的 EN 16931 CIUS 相互独立。

数字签名（2 个工具）

工具	描述
sign_fattura_xades	应用 XAdES-BES 封装式 XML 签名（.xml）。需要 PKCS#12 证书。
sign_fattura_cades	应用 CAdES-BES CMS/PKCS#7 附加式签名（.xml.p7m）。需要 PKCS#12 证书。

SDI 接受这两种签名格式（Specifiche tecniche SDI v1.8.4，第 2.1 节）。 支持双模式：签名微服务（密钥不会进入 MCP 进程）或直接加载 PKCS#12。 需要 cryptography>=42.0.0（通过 mcp-einvoicing-core 的 [xml-sign] 附加项安装）。

SDI 集成（5 个工具）

工具	描述
submit_to_sdi	通过 SDICoop SOAP（mTLS）向 SDI 提交已签名的发票
check_sdi_status	按 IdentificativoSDI 查询提交状态
parse_sdi_notification	解析 SDI 通知 XML（RC/NS/MC/NE/EC/SE/DT/MT/AT）；已知的废弃代码（如 00327、Gruppo IVA CodiceFiscale）会附带补充说明 reference_note
send_esito_committente	向 SDI 发送接受（EC01）或拒绝（EC02）通知
get_sdi_channel_info	显示当前 SDI 通道配置

生产环境使用需要获得 AdE 认证。通过环境变量 SDI_CERT_PATH、SDI_CERT_PASSWORD、SDI_ENVIRONMENT（test/production）和 SDI_ENDPOINT_URL（覆盖配置）进行配置。

Conservazione sostitutiva / 归档（5 个工具）

工具	描述
archive_invoice	归档已签名的发票，并计算 SHA-256 哈希值，保留 10 年
retrieve_archived_invoice	按 ID 检索已归档的文档
verify_archive_integrity	验证已归档文档的 SHA-256 哈希完整性
list_archived_invoices	列出所有已归档的发票
build_pacchetto_versamento	构建 PdV ZIP 归档包，以便转交给获得 AgID 认证的保存服务商

根据 AgID circular 65/2014 和 DM 17/06/2014，电子发票必须至少归档 10 年。本地文件系统后端仅用于开发；生产环境需要集成获得 AgID 认证的 conservazione 服务提供商。

使用示例

示例 1：生成完整的 B2B 发票

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 }

示例 2：包含预扣税的专业发票

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"
  }

示例 3：查询 VAT 豁免代码

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" },
    ...
  ]

架构

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)

厂商中立性

此服务端直接实现标准：在本地构建、验证和签署文档。它不是商业开票平台的客户端，您的签名密钥和凭据绝不会离开您自己的基础设施。

发票通过您自己的认证，经由 SDICoop 直接发送至 SdI；整个过程不涉及中间方。

支持的标准

资源	链接
FatturaPA 规范	fatturapa.gov.it
官方 XSD v1.2.3	Schema v1.2.2，Agenzia delle Entrate
Specifiche Tecniche（Allegato A）1.9.1，自 2026-05-15 起生效	Agenzia delle Entrate — 与 XSD 分离的文件；不会对其进行更改
XML 命名空间	http://ivaservizi.agenziaentrate.gov.it/docs/xsd/fatture/v1.2
SDI，Sistema di Interscambio	Agenzia delle Entrate
预扣税（ritenuta d'acconto）	Art. 25 DPR 600/73，Modello 770

测试

# 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

贡献

欢迎贡献 — 请参阅 CONTRIBUTING.md 了解指南。

其他电子发票 MCP 服务

国家/地区	服务
🌍 全球	mcp-einvoicing-core
🇧🇪 比利时	mcp-einvoicing-be
🇧🇷 巴西	mcp-nfe-br
🇫🇷 法国	mcp-facture-electronique-fr
🇩🇪 德国	mcp-einvoicing-de
🇮🇳 印度	mcp-einvoicing-in
🇮🇹 意大利	mcp-fattura-elettronica-it
🇲🇽 墨西哥	mcp-cfdi-mx
🇵🇱 波兰	mcp-ksef-pl
🇸🇬 新加坡	mcp-invoicenow-sg
🇪🇸 西班牙	mcp-facturacion-electronica-es
🇦🇪 阿联酋	mcp-einvoicing-ae

许可证

本项目采用 Apache 2.0 许可证分发。完整详情请参阅 LICENSE 文件。完整版本历史请参阅 CHANGELOG.md。