mcp-nfe-br

mcp-nfe-br 🇧🇷

English | Portugues (Brasil)

---

はじめに

mcp-nfe-br は、ブラジルの電子税務書類である NF-e（modelo 55）、NFC-e（modelo 65）、NFS-e Nacional（ADN）、CT-e（modelo 57） の発行および検証ツールを提供する MCP（Model Context Protocol） サーバーです。このサーバーは、mcp-einvoicing-core を基盤とする mcp-einvoicing-*／mcp-*-* ファミリーの一部です。mcp-einvoicing-core は、基本データモデル、HTTP／OAuth2 ユーティリティ、共有 MCP サーバー基盤を提供します。

現在の状況（v0.6.5）： NF-e／NFC-e（modelo 55/65、schema 4.00）および NFS-e Nacional（ADN、schema v1.01）の生成、ICP-Brasil 署名、XSD 検証、条件付きの SEFAZ／ADN 送信を実装しています。NF-e／NFC-e では、PL_010d のベースに加えて、010e_v.1.02 のスキーマ差分（DANFE Simplificado Tipo 2 — tpImp=6、cIndOp、ISUFEmit、SEFAZ のアラートメッセージ応答グループ）と、010f_v.1.04 の差分（NT 2026.007 — IBS／CBS のみの課税対象となる納税者では emit/IE を任意に変更、produção 2026-11-03）にも対応しています。CT-e（modelo 57） の生成／署名／検証および SEFAZ イベント送信（cancelamento、Carta de Correção）は v0.6.0 から追加されました。v1 の対象範囲は意図的に限定されており、modal rodoviário のみ、ICMS CST 00 のみ、および 同梱・検証済み CT-e ウェブサービスエンドポイントテーブルなし です（SEFAZ CT-e の呼び出しにはすべて、明示的な endpoint_override が必要です）。フィールドごとの詳細については、以下の「CT-e（modelo 57）」ツールのセクションを参照してください。

インストール

要件

• Python ≥ 3.11
• mcp-einvoicing-core（依存関係として自動的にインストールされます）

uv を使用する場合（推奨）

uv add mcp-nfe-br

pip を使用する場合

pip install mcp-nfe-br

ソースからインストールする場合

git clone https://github.com/cmendezs/mcp-nfe-br.git
cd mcp-nfe-br
uv sync --all-extras

設定

このサーバーの実行に認証情報は必要ありません。以下の環境変数は、安全性／ログ設定を切り替える任意の設定です。

環境変数

変数	説明	デフォルト
BR_READ_ONLY	マスタースイッチです。1 に設定すると、すべてのサブ形式にわたって書き込みツールを無効にします。対象は NF-e／NFC-e（br__submit_nfe、br__distribute_dfe）、NFS-e（br__submit_nfse、br__cancel_nfse）、CT-e（br__submit_cte、br__cancel_cte、br__correct_cte）です。探索時に安全なモードとして使用できます。SEFAZ 環境（本番／検証）は、呼び出しごとに tp_amb 引数で選択します。	—
BR_CTE_READ_ONLY	1 に設定すると、CT-e の書き込みツール（br__submit_cte、br__cancel_cte、br__correct_cte）のみを無効にし、NF-e／NFS-e の書き込みは有効なままにします。BR_READ_ONLY とは独立しています。どちらか一方を 1 に設定すれば CT-e の書き込みをブロックできます。両方を設定する必要はありません。	—
LOG_LEVEL	ログレベル：DEBUG、INFO、WARNING、ERROR	INFO

Claude Desktop との連携

このサーバーを Claude で使用するには、次の設定を claude_desktop_config.json ファイルに追加します。

{
  "mcpServers": {
    "nfe-br": {
      "command": "uvx",
      "args": ["mcp-nfe-br"]
    }
  }
}

ローカル開発用インストールの場合：

{
  "mcpServers": {
    "nfe-br": {
      "command": "uv",
      "args": ["run", "mcp-nfe-br"],
      "cwd": "/path/to/mcp-nfe-br"
    }
  }
}

Cursor との連携

Cursor は stdio 経由で MCP サーバーをサポートしています。次の場所に設定を追加します。

• グローバル（すべてのプロジェクト）：~/.cursor/mcp.json
• プロジェクト（このリポジトリのみ）：.cursor/mcp.json

{
  "mcpServers": {
    "nfe-br": {
      "command": "uvx",
      "args": ["mcp-nfe-br"]
    }
  }
}

変更を適用するには、Cursor ウィンドウを再読み込みします（Ctrl+Shift+P を押してから Reload Window を選択）。

Kiro との連携

Kiro は専用の設定ファイルを介して MCP サーバーをサポートしています。次の 2 つの設定レベルがあります。

• グローバル（すべてのプロジェクト）：~/.kiro/settings/mcp.json
• ワークスペース（このリポジトリのみ）：.kiro/settings/mcp.json

{
  "mcpServers": {
    "nfe-br": {
      "command": "uvx",
      "args": ["mcp-nfe-br"],
      "disabled": false,
      "autoApprove": []
    }
  }
}

ファイルは保存時に自動的に再読み込みされます。コマンドパレット（Cmd+Shift+P／Ctrl+Shift+P）を開いてから MCP を選択して、設定を開くこともできます。

利用可能なツール

br__validate_cpf

Receita Federal の modulo 11 アルゴリズムを使用して、個人納税者識別番号である CPF（Cadastro de Pessoas Físicas）を検証します。

パラメーター	型	必須	説明
cpf	string	はい	./- の区切り文字の有無を問わない CPF

成功時は valid=True と整形済みの値（11 桁）、失敗時は valid=False とポルトガル語のエラーメッセージを含む TaxIdValidationResult を返します。

---

br__validate_cnpj

法人納税者識別番号である CNPJ（Cadastro Nacional da Pessoa Jurídica）を検証します。従来の数値形式（14 桁）と、NT 2026.004（PL_010d）で導入された英数字形式の両方に対応しています。英数字形式は、ホモロゲーション環境では 2026-06-01 から、本番環境では 2026-07-01 から有効です。

パラメーター	型	必須	説明
cnpj	string	はい	.///- の区切り文字の有無を問わない CNPJ

成功時は valid=True と整形済みの値（14 文字）、失敗時は valid=False とポルトガル語のエラーメッセージを含む TaxIdValidationResult を返します。

⚠️ [未検証]：英数字形式の CNPJ のチェックディジットアルゴリズムは、一次資料（「NT Conjunta DFe 2025.001」）をまだローカルで入手できないため、二次資料に基づいて実装されています。

---

br__generate_nfe

BRInvoice オブジェクトから、署名されていない NF-e/NFC-e 4.00 ドキュメント（<NFe><infNFe>…</infNFe></NFe>）を生成します。

パラメーター	型	必須	説明
invoice	object	はい	BRInvoice ドキュメント（modelo 55 または 65、グループ ide/emit/dest/det/total/transp/pag）

{"xml": ..., "chave_acesso": ..., "warnings": [...]} を返します。ポルトガル語の警告では、ドキュメントが 署名されていない（ICP-Brasil）こと、および SEFAZ に送信されていないことを通知します。これら 2 つの手順は、別のプロセスで行う必要があります。

品目ごとの税グループに関するフェーズ 1 の対応範囲：

税	対応コード	動作
ICMS	CST 00（通常の課税制度）または CSOSN 102（Simples Nacional）	その他のコードでは DocumentGenerationError が発生します
PIS/COFINS	CST 01/02（税率ベース）または 04-09（非課税）	pis_cst/cofins_cst が None の場合、グループは省略されます
IPI	CST 00/49/50/99（課税）またはその他（非課税）	ipi_cst が None の場合、グループは省略されます

[NEED: IBS/CBS/Imposto Seletivo — Grupo UB/W03 (NT 2025.002-RTC) not yet modeled]。

---

br__validate_nfe_xml

公式の PL_010d XSD に対して NF-e/NFC-e 4.00 XML ドキュメントを検証します。この XSD には PL_010e_v.1.02 および PL_010f_v.1.04 の差分が適用されています（ローカルの「未署名」バリアント。下記の注記を参照）。

パラメーター	型	必須	説明
xml_content	string	いいえ*	文字列としての XML
xml_base64	string	いいえ*	Base64 エンコードされた XML

* xml_content/xml_base64 のいずれか一方だけを指定する必要があります。

{"valid": bool, "errors": [...], "metadata": {"schema_version": ...}} を返します。

[推論]：公式 XSD（PL_010d の nfe_v4.00.xsd/leiauteNFe_v4.00.xsd）では、<ds:Signature> が <NFe> の必須子要素として指定されています。フェーズ 1 では未署名のドキュメントを生成するため、このツールはローカルで派生させたコピー（nfe_v4.00_unsigned.xsd）に対して検証します。このコピーでは、<ds:Signature> が任意（minOccurs="0"）に変更されています。署名済みドキュメントの検証（将来のフェーズ）では、変更していない公式 XSD を使用してください。

---

br__build_access_key

cUF、dhEmi、発行者の CNPJ、モデル、シリーズ、文書番号の各要素から、モジュロ 11 のチェックディジットを含むアクセスキー（chNFe、44 文字）を生成します。

パラメーター	型	必須	説明
c_uf	string	はい	IBGE 州コード（2 桁）
dh_emi	string	はい	発行日時（ISO 8601）
cnpj	string	はい	発行者の CNPJ（数値または英数字の PL_010d）
modelo	string	はい	55（NF-e）または 65（NFC-e）
serie	string	はい	文書のシリーズ
nnf	string	はい	文書番号
tp_emis	string	いいえ	発行タイプ（デフォルトは "1"）
c_nf	string	いいえ	ランダムな数値コード（cNF、8 桁）。省略時は自動生成されます

{"chave_acesso": ..., "cnf": ...} を返します。

CT-e（モデル 57）ツール

CT-e（電子輸送知識証明書）の対応は v0.6.0 で開始されました。v1 の範囲は意図的に限定されています。対象は道路輸送モダリティのみ（他のモダリティではエラーが発生します）、ICMS CST 00（通常課税）のみであり、SEFAZ CT-e エンドポイントの一覧は同梱も検証もされていません。そのため、以下の SEFAZ 呼び出しにはすべて、明示的な endpoint_override が必要です。v0.7.0 以降、br__generate_cte は NT 2026.002 で導入された消費税制改革（IBS/CBS）のフィールド（imp/IBSCBS、emit/ISUFEmit、ide/tpPagAnt+gPagAntecipado）も受け付けるようになりました。NT の自己完結型の業務ルールはモデルレイヤーで適用されますが、SEFAZ のライブデータベース照会が必要なルールはチェックされません。

br__generate_cte

BRCTeDocument オブジェクトから未署名の CT-e 4.00 文書（<CTe><infCte>…</infCte></CTe>）を生成します。

パラメーター	型	必須	説明
cte	object	はい	BRCTeDocument（モデル 57、道路輸送モダリティ、ICMS CST 00）

{"xml": ..., "chave_acesso": ..., "warnings": [...]} を返します。

br__validate_cte_xml

同梱の PL_CTe_400 XSD に照らして CT-e 4.00 XML 文書を検証します（<ds:Signature> の有無に基づき、未署名用または公式の署名済みスキーマを自動選択します）。

パラメーター	型	必須	説明
xml_content	string	いいえ*	文字列形式の XML
xml_base64	string	いいえ*	Base64 エンコードされた XML

* xml_content と xml_base64 のどちらか一方だけを指定する必要があります。

br__consult_cte_sefaz_status

SEFAZ CT-e ウェブサービスの稼働状況（CTeStatusServicoV4）を確認します。読み取り専用で、確認は不要です。

br__consult_cte

アクセスキーを使って CT-e のステータスを照会します（CTeConsultaV4）。読み取り専用で、確認は不要です。一括データ取得ではなく、すでに特定されている 1 件の文書を照会します。

br__submit_cte

署名済み CT-e を SEFAZ の承認サービスに送信します（CTeRecepcaoSincV4、同期）。CT-e MOC に従い、送信前にペイロードは自動的に GZip 圧縮され、Base64 エンコードされます。2 段階の確認（ConfirmationGate）と BR_CTE_READ_ONLY による制御対象です。

br__cancel_cte

承認済み CT-e の取消しを要求します（イベント 110111、CTeRecepcaoEventoV4）。cStat=135 は取消しが承認されたことを示します。制御対象です。

br__correct_cte

電子訂正状（Carta de Correção Eletrônica）を発行します（イベント 110110、CTeRecepcaoEventoV4）。CONVÊNIO/SINIEF 06/89 の第 58-B 条により、CC-e では税額、当事者の登録情報、発行日または出発日を変更できません。制御対象です。

未実装：br__distribute_cte_dfe（CTeDistribuicaoDFe）。同梱の仕様ではリクエストペイロードの形式は確認できますが、ウェブサービスのメソッド名、WSDL 名前空間、メッセージラッパー要素は確認できません。

アーキテクチャ

mcp-nfe-br/
├── src/
│   └── mcp_nfe_br/
│       ├── __init__.py
│       ├── server.py              # MCP entry point and tool registration
│       ├── models/
│       │   ├── __init__.py
│       │   └── invoice.py         # BRInvoice, BRInvoiceLine, NFeModelo, TipoOperacao
│       ├── standards/
│       │   ├── __init__.py
│       │   └── nfe_generator.py   # NFeGenerator — generates unsigned NF-e/NFC-e 4.00
│       ├── validators/
│       │   ├── __init__.py
│       │   └── nfe_xsd.py         # NFeXSDValidator — validates against PL_010d XSD (unsigned variant)
│       ├── schemas/nfe/           # Bundled XSDs (official + "_unsigned" variants)
│       ├── tools/
│       │   ├── __init__.py
│       │   ├── validation.py      # br__validate_cpf, br__validate_cnpj
│       │   └── generation.py      # br__generate_nfe, br__validate_nfe_xml, br__build_access_key
│       └── utils/
│           ├── __init__.py
│           ├── document_ids.py    # validate_cpf, validate_cnpj
│           └── access_key.py      # build_access_key, access_key_check_digit
├── tests/
│   ├── conftest.py
│   ├── fixtures/
│   ├── test_tools/
│   │   ├── test_validation.py
│   │   └── test_generation.py
│   ├── test_standards/
│   │   └── test_nfe_generator.py
│   ├── test_validators/
│   │   └── test_nfe_xsd.py
│   └── test_utils/
│       └── test_access_key.py
├── specs/nfe/                     # Normative material (XSDs, MOC, Technical Notes, not published)
├── audit/
│   ├── audit_vs_core.py
│   └── report.json
├── .github/workflows/publish.yml
├── pyproject.toml
├── RELEASE.md
└── LICENSE

mcp-einvoicing-coreとの関係

mcp-einvoicing-coreが提供するもの：

• 請求書、関係者、明細項目、検証結果の基本となるPydanticモデル（InvoiceDocument、InvoiceLineItem、TaxIdValidationResult）
• 共通のMCPサーバーインフラストラクチャ（EInvoicingMCPServer）
• HTTP/OAuth2クライアント、トークンキャッシュ、構造化ログ、例外階層

mcp-nfe-brが追加するブラジル固有のロジック：

• BRInvoice（InvoiceDocumentを拡張。NF-e/NFC-eにはEN 16931の系譜がないため）
• BRInvoiceLineのグループIフィールド（NCM、CFOP、ICMS/IPI/PIS/COFINS）
• CPF/CNPJの検証（NT 2026.004で導入された英数字のCNPJを含む）

ベンダー中立性

このサーバーは標準そのものを実装しています。ドキュメントの作成、検証、署名はローカルで行います。商用の請求書プラットフォーム向けのクライアントではなく、署名キーと認証情報が自社のインフラストラクチャの外に出ることはありません。

請求書は、自社のデジタル証明書を使用してSEFAZ（NF-e/NFC-e）およびCT-e SEFAZエンドポイントに直接送信されます。仲介者は介在しません。

コントリビューション

コントリビューションを歓迎します。重要な変更については、プルリクエストを送信する前にIssueを作成してご相談ください。

git clone https://github.com/cmendezs/mcp-nfe-br.git
cd mcp-nfe-br
uv sync --all-extras
uv run pytest
uv run ruff check src/mcp_nfe_br tests audit
uv run mypy src/mcp_nfe_br

その他の電子請求書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を参照してください。