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エージェント（Claude、IDE）が、Sistema di Interscambio（SDI）の技術仕様に直接準拠したB2B、B2G、越境電子請求書を生成、検証、分析できます。電子請求書MCPサーバー向けの共有基盤ライブラリであるmcp-einvoicing-coreを基盤に構築されています。

注：「Specifiche Tecniche」（AdE Allegato Aの管理項目／コード体系に関する文書）とXSDスキーマは、それぞれ独立したバージョン番号を持つ別個の成果物です。Specifiche Tecniche 1.9.1（2026-05-15施行）ではXSDは変更されておらず、同梱されているスキーマは引き続きv1.2.3です。

これは、FatturaPA XML文書のライフサイクル全体をカバーする43個のツールを提供するModel Context Protocol（MCP）サーバーです。送信ヘッダーの構築、販売者／購入者の検証（Gruppo IVA／VATグループの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通知の解析、ならびに保存義務に準拠した保管（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 サーバーをサポートしています。次の 2 つの設定レベルがあります。

• グローバル（すべてのプロジェクト）：~/.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 は起動時にシェル環境変数を解決します。

利用可能なツール

ヘッダー：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 の scarto コード 00327 に関する構造上の前提条件について警告します）
get_regime_fiscale_codes	有効なすべての RegimeFiscale コードと説明（RF01-RF19）を返します
validate_partita_iva	イタリアの VAT 番号（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	VAT 免除に関するすべての 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	FatturaPA XML 文字列を公式 XSD スキーマ v1.2.3 に照らして検証します
parse_fattura_xml	既存の FatturaPA XML 文字列を解析し、構造化された JSON dict を返します
export_to_json	解析済みの FatturaPA 構造を整形された JSON 形式でエクスポートします
validate_partita_iva_format	Partita IVA の形式と Luhn 方式に類似したチェックサム（11 桁のイタリア VAT 番号）を検証します
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 を構造化 dict に解析します

簡易請求書（art. 21-bis DPR 633/72）は、400 EUR 以下（税額込み）の取引に有効です。 通常の 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）を解析します。既知の scarto コード（例：00327、Gruppo IVA CodiceFiscale）には補足の reference_note が含まれます
send_esito_committente	受諾（EC01）または拒否（EC02）を SDI に送信します
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	AgID 認定の保存機関への移管用に PdV ZIP アーカイブを作成します

AgID circolare 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 とは別の成果物であり、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 をご覧ください。