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-nacionalMCP 客户端中的配置示例 （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-nacionalMCP 终端将在 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-nacionalMCP 终端将在 http://localhost:3000/mcp.
Dockerfile 已定义MCP_TRANSPORT=streamable-http,MCP_HOST=0.0.0.0eMCP_PORT=3000默认 。
安全
⚠️ 数字证书是一项关键资产。 它具有法律效力，并在联邦税务局和其他机构面前代表您的公司或个人的身份。对待它与对待主密码一样小心。
基本指导方针
- 从未版本或证书(
.pfx/.p12或您的 Git 仓库密码。 添加*.pfx,*.p12e.env你 的.gitignore. - 不要公开 HTTP 服务器 。 无模式
streamable-http服务器没有自己的身份验证功能。 请只在下列情况下访问 。127.0.0.1或使用经过身份验证的反向代理（使用mTLS，API密钥等）来保护它。 - 使用环境变量或秘密管理器 提供证书的密码 。避免将其作为命令行参数传递，因为它可能在shell历史记录和进程列表中可见（
ps). - 以只读方式挂载证书 无Docker（标志
:ro降低意外变更的风险。 - 限制证书文件的权限 文件系统（
chmod 400 certificado.pfx). - 监视证书过期 。 数字证书的有效期（通常为1-3年）。有一个更新的过程。
- 本地 XML 和 PDF 存储 ： 下载的文件保存在目录中
storage/确保该目录拥有适当的权限，并根据您组织的隐私政策处理税务数据。