JinDaGe - mcp-nfse-nacional MCP Details

article

README

🚀 MCP全国电子服务发票查询系统

MCP服务器用于在国家电子服务发票门户网站（nfse.gov.br）上查询电子服务发票（NFSe）。它允许人工智能代理使用数字证书e - CNPJ/e - CPF进行身份验证，并查询、查看详情以及下载已开具的NFSe的PDF文件。

🚀 快速开始

本系统提供便捷的电子服务发票查询功能，通过MCP协议暴露相关工具，可按以下步骤操作使用。

✨ 主要特性

可用工具

服务器通过MCP协议提供了三种工具： | 工具 | 描述 | 参数 | |------|------|------| | nfse_buscar | 搜索指定时间段内开具的NFSe。返回每张发票的日期、接收方、金额、状态和密钥列表。 | data_inicio（YYYY - MM - DD），data_fim（YYYY - MM - DD） | | 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执行

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/ 目录中。请确保该目录具有适当的权限，并根据组织的隐私政策处理财务数据。

mcp-nfse-nacional