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