MCP Nfse Nacional

🚀 MCP全國電子服務發票查詢系統

MCP服務器用於在國家電子服務發票門戶網站（nfse.gov.br）上查詢電子服務發票（NFSe）。它允許人工智能代理使用數字證書e - CNPJ/e - CPF進行身份驗證，並查詢、查看詳情以及下載已開具的NFSe的PDF文件。

🚀 快速開始

本系統提供便捷的電子服務發票查詢功能，通過MCP協議暴露相關工具，可按以下步驟操作使用。

✨ 主要特性

可用工具

服務器通過MCP協議提供了三種工具：

身份驗證由系統自動管理。首次調用時進行登錄，如果會話過期（身份驗證錯誤），系統會自動透明地重新嘗試登錄。

📦 安裝指南

環境變量設置

你可以在項目根目錄的 .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密鑰等）進行保護。
• 使用環境變量或密鑰管理器 來提供證書密碼。避免將其作為命令行參數傳遞，因為它可能會在shell歷史記錄和進程列表（ps）中可見。
• 在Docker中以只讀方式掛載證書（:ro 標誌），以減少意外修改的風險。
• 限制證書文件在文件系統中的權限（chmod 400 certificado.pfx）。
• 監控證書的有效期。 數字證書有有效期（通常為1到3年）。請制定更新流程。
• 本地存儲XML和PDF文件：下載的文件保存在 storage/ 目錄中。請確保該目錄具有適當的權限，並根據組織的隱私政策處理財務數據。