MCP NFSe Nacional

mcp-nfse-nacional

ポータル (nfse.gov.br) で電子サービス請求書（NFSe）を照会するための MCP サーバーです。AI エージェントが e-CNPJ/e-CPF デジタル証明書で認証し、発行済みの NFSe を検索、詳細表示、PDF ダウンロードできるようにします。

利用可能なツール

サーバーは MCP プロトコルを通じて、次の 3 つのツールを公開します。

ツール	説明	パラメーター
nfse_buscar	期間を指定して発行済みの NFSe を検索します。各請求書の日付、宛先、金額、ステータス、キーを含む一覧を返します。	data_inicio (YYYY-MM-DD), data_fim (YYYY-MM-DD)
nfse_detalhes	キーを指定して NFSe の詳細を取得します。ヘッダー、発行者、金額、DPS を返し、XML をローカルに保存します。	chave (string)
nfse_pdf	キーを指定して NFSe の PDF（DANFSe）をダウンロードします。ローカルに保存した PDF ファイルのパスを返します。	chave (string)

認証は自動的に管理されます。初回の呼び出し時にログインが実行され、セッションの有効期限が切れた場合（認証エラー）、再ログインが自動的に行われます。

環境変数

変数	必須	デフォルト	説明
CERT_FILE	はい	—	デジタル証明書ファイル（.pfx / .p12）へのパスです。プロジェクトディレクトリからの相対パス、または絶対パスを指定します。
CERT_PASSWORD	はい	—	デジタル証明書のパスワードです。
MCP_TRANSPORT	いいえ	stdio	MCP サーバーのトランスポートモードです。指定できる値は stdio または streamable-http です。
MCP_HOST	いいえ	127.0.0.1	HTTP サーバーのバインドアドレスです（streamable-http モードのみ）。
MCP_PORT	いいえ	3000	HTTP サーバーのポートです（streamable-http モードのみ）。
STORAGE_PATH	いいえ	./storage	ダウンロードした XML および PDF を保存するディレクトリです。

プロジェクトのルートにある .env ファイルで変数を定義できます。

npx 経由での実行

stdio モード（デフォルト）

MCP クライアント（Claude Desktop、VS Code など）との直接連携に最適です。

CERT_FILE=./certificado.pfx CERT_PASSWORD=sua_senha npx -y mcp-nfse-nacional

MCP クライアント（mcp.json）での設定例：

{
  "servers": {
    "nfse-nacional": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "mcp-nfse-nacional"],
      "env": {
        "CERT_FILE": "/caminho/absoluto/para/certificado.pfx",
        "CERT_PASSWORD": "sua_senha"
      }
    }
  }
}

Streamable HTTP モード

サーバーが HTTP 接続を待ち受ける必要がある環境に最適です。

CERT_FILE=./certificado.pfx CERT_PASSWORD=sua_senha MCP_TRANSPORT=streamable-http MCP_HOST=127.0.0.1 MCP_PORT=3000 npx -y mcp-nfse-nacional

MCP エンドポイントは http://127.0.0.1:3000/mcp で利用できます。

MCP クライアント（mcp.json）での設定例：

{
  "servers": {
    "nfse-nacional": {
      "type": "streamable-http",
      "url": "http://127.0.0.1:3000/mcp"
    }
  }
}

Docker 経由での実行（Streamable HTTP）

イメージのビルド

docker build -t mcp-nfse-nacional .

実行

docker run -d \
  --name mcp-nfse-nacional \
  -p 3000:3000 \
  -v /caminho/para/certificado.pfx:/app/certificado.pfx:ro \
  -v /caminho/para/storage:/app/storage \
  -e CERT_FILE=certificado.pfx \
  -e CERT_PASSWORD=sua_senha \
  mcp-nfse-nacional

MCP エンドポイントは http://localhost:3000/mcp で利用できます。

Dockerfile では、デフォルトで MCP_TRANSPORT=streamable-http、MCP_HOST=0.0.0.0、MCP_PORT=3000 が設定されています。

セキュリティ

⚠️ デジタル証明書は重要な資産です。 法的効力を持ち、連邦歳入庁やその他の機関に対して、企業または個人の身元を証明するものです。マスターパスワードと同じように慎重に取り扱ってください。

重要なガイドライン

• 証明書（.pfx / .p12）やそのパスワードを Git リポジトリにコミットしないでください。 *.pfx、*.p12、.env を .gitignore に追加してください。
• HTTP サーバーをインターネットに公開しないでください。 streamable-http モードでは、サーバーに独自の認証機能がありません。127.0.0.1 からのみアクセスできるようにするか、認証機能付きのリバースプロキシ（mTLS、API key など）で保護してください。
• 証明書のパスワードは環境変数またはシークレットマネージャーで指定してください。 コマンドライン引数として渡すのは避けてください。シェルの履歴やプロセス一覧（ps）に表示される可能性があります。
• Docker では証明書を読み取り専用でマウントし（フラグ :ro）、誤って変更されるリスクを最小限に抑えてください。
• ファイルシステム上で証明書ファイルのアクセス権を制限してください（chmod 400 certificado.pfx）。
• 証明書の有効期限を監視してください。 デジタル証明書には有効期間（通常 1～3 年）があります。更新の手順を用意してください。
• XML と PDF のローカル保存： ダウンロードしたファイルは storage/ ディレクトリに保存されます。このディレクトリに適切なアクセス権を設定し、組織のプライバシーポリシーに従って税務データを取り扱ってください。