MCP NFSe Nacional

Name: MCP NFSe Nacional
Author: SamuelMoraesF

本地服务

github.com/SamuelMoraesF金融数据1837 周前更新

代码仓库

关于 MCP NFSe Nacional

MCP NFSe Nacional 是面向 Agent 的 MCP 服务，用于查询巴西国家门户 nfse.gov.br 上的电子服务发票。它支持数字证书认证、发票检索与详情查询，并可在本地保存 XML 和 PDF。

主要功能

01按日期范围搜索已开具的 NFSe
02查询发票详情并保存 XML
03下载 DANFSe PDF
04自动进行证书登录和会话续期

适用场景

01查看某一时段开具的发票
02按发票密钥获取数据和 XML
03保存发票 PDF 以供本地处理

MCP 相关

它通过三个 MCP 工具提供已开具 NFSe 搜索、发票详情与 XML 保存、DANFSe PDF 下载功能。支持 stdio 和 Streamable HTTP 传输。

#brazil #gov-br #nfse #nfse-nacional #nfe

配置

本地服务的配置在各客户端中通用，复制后粘贴到客户端的 MCP 配置文件即可。

mcp.json · 通用配置

{
  "mcpServers": {
    "nfse-nacional": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-nfse-nacional"
      ],
      "env": {
        "CERT_PASSWORD": "<CERT_PASSWORD>",
        "CERT_FILE": "<CERT_FILE>",
        "NODE_OPTIONS": "<NODE_OPTIONS>",
        "MCP_PORT": "<MCP_PORT>",
        "STORAGE_PATH": "<STORAGE_PATH>"
      }
    }
  }
}

启动命令npx -y mcp-nfse-nacional

需要配置的环境变量

CERT_PASSWORD密钥Senha do certificado digital (e-CNPJ/e-CPF) em formato PFX

CERT_FILECaminho para o arquivo do certificado digital (.pfx)

NODE_OPTIONSOpções do Node.js (use --openssl-legacy-provider para compatibilidade com certificados)

MCP_PORTPorta do servidor HTTP

STORAGE_PATHDiretório onde os XMLs e PDFs baixados serão armazenados

本地服务需要在你的电脑上安装运行环境（如 Node.js 18+）。各客户端的配置文件位置不同，请参考客户端文档。

安装包

npmmcp-nfse-nacional1.0.3stdio

ocidocker.io/samuelmoraesf/mcp-nfse-nacional:1.0.3Streamable HTTP

工具

还没有获取到工具列表

本地服务需要在你的电脑上运行后才能读取工具，维护者暂未提供工具列表。

详细介绍

mcp-nfse-nacional

用于在国家门户网站 (nfse.gov.br) 查询电子服务税务发票（NFSe）的 MCP 服务。它允许 AI Agent 使用 e-CNPJ/e-CPF 数字证书进行身份验证，并查询、查看详情和下载已开具 NFSe 的 PDF。

可用工具

该服务通过 MCP 协议提供三种工具：

工具	描述	参数
`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 等）保护它。
使用环境变量或 secrets manager 提供证书密码。避免将密码作为命令行参数传递，因为它可能会出现在 shell 历史记录和进程列表（ps）中。
在 Docker 中将证书挂载为只读（标志 :ro），以尽量降低意外修改的风险。
限制文件系统中证书文件的权限（chmod 400 certificado.pfx）。
监控证书的有效期。 数字证书有有效期（通常为 1 至 3 年）。请制定续期流程。
XML 和 PDF 的本地存储： 下载的文件会保存在 storage/ 目录中。请确保该目录具有适当的权限，并按照组织的隐私政策处理税务数据。