MCP Nfse Nacional

🚀 mcp-nfse-nacional

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

🚀 クイックスタート

このサーバーを使用することで、AIエージェントはデジタル証明書を用いて全国ポータルでNFSeの照会やダウンロードが可能になります。以下に、サーバーの機能や実行方法を説明します。

✨ 主な機能

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

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

📦 インストール

環境変数の設定

環境変数は、プロジェクトのルートにある .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キーなど）で保護してください。
• 環境変数またはシークレットマネージャーを使用して デジタル証明書のパスワードを提供してください。コマンドライン引数として渡すのは避けてください。なぜなら、シェルの履歴やプロセスリスト（ps）に表示される可能性があるからです。
• Dockerでデジタル証明書を読み取り専用でマウントしてください（:ro フラグ）。これにより、誤った変更のリスクを最小限に抑えます。
• デジタル証明書ファイルのアクセス権を制限してください（chmod 400 certificado.pfx）。
• デジタル証明書の有効期限を監視してください。 デジタル証明書には有効期限があります（通常は1〜3年）。更新プロセスを用意してください。
• XMLとPDFのローカル保存：ダウンロードされたファイルは storage/ ディレクトリに保存されます。このディレクトリに適切なアクセス権が設定されていること、および財務データが組織のプライバシーポリシーに従って処理されることを確認してください。