AI导哈

电子发票查询服务

MCP Server用于在国家门户网站上查询电子服务发票（NFSe），允许AI代理使用数字证书e-CNPJ/e-CPF进行认证，并查询、详细查看和下载已发出的NFSe的PDF文件。

  • by SamuelMoraesF
  • TypeScript
  • 混合部署
  • 18 星标
  • 更新于
在 GitHub 查看 SamuelMoraesF/mcp-nfse-nacional

使用说明

mcp nfse国家

MCP 服务器用于查询国家门户网站上的电子服务税务报表 （NFSe） （nfse.gov.br).它允许 AI 代理使用 e-CNPJ/e-CPF 数字证书进行身份验证，并查看、详细说明和下载发布的 NFSe PDF。

可用工具

服务器通过MCP协议暴露三个工具：

工具 描述 参数
nfse_buscar 查找一段时间内发行的 NFSe。返回每个笔记的日期、收件人、值、状态和密钥列表。 data_inicio （YYYY-MM-DD）， data_fim （年-月-日）
nfse_detalhes 从您的密钥获取 NFSe 的完整详细信息。返回标题、发件人、值、DPS，并在本地保存 XML。 chave （字符串）
nfse_pdf 从您的密钥下载NFSe的PDF（DANFSe）。返回本地保存的 PDF 文件的路径。 chave （字符串）

验证是自动管理的。登录是在第一次呼叫时进行的，如果会话过期（身份验证错误），则会以透明方式重新尝试登录。

环境变量

| 变量 | 标准 | 描述 | |---|---|---|---| | 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 运行

标准模式（ 默认）

与 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"
      }
    }
  }
}

Modo流式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执行（流式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 e MCP_PORT=3000 默认 。

安全

⚠️ 数字证书是一项关键资产。 它具有法律效力，并在联邦税务局和其他机构面前代表您的公司或个人的身份。对待它与对待主密码一样小心。

基本指导方针

  • 从未版本或证书(.pfx / .p12或您的 Git 仓库密码。 添加 *.pfx, *.p12 e .env 你 的 .gitignore.
  • 不要公开 HTTP 服务器 。 无模式 streamable-http服务器没有自己的身份验证功能。 请只在下列情况下访问 。 127.0.0.1 或使用经过身份验证的反向代理（使用mTLS，API密钥等）来保护它。
  • 使用环境变量或秘密管理器 提供证书的密码 。避免将其作为命令行参数传递，因为它可能在shell历史记录和进程列表中可见（ps).
  • 以只读方式挂载证书 无Docker（标志 :ro降低意外变更的风险。
  • 限制证书文件的权限 文件系统（chmod 400 certificado.pfx).
  • 监视证书过期 。 数字证书的有效期（通常为1-3年）。有一个更新的过程。
  • 本地 XML 和 PDF 存储 ： 下载的文件保存在目录中 storage/确保该目录拥有适当的权限，并根据您组织的隐私政策处理税务数据。

相关 MCP