mcp-nfse-nacional — Claude Code MCP server
This MCP server searches NFSe on the national portal, reads invoice details, and downloads PDFs. It suits agent-driven access to electronic service invoices.
claude mcp add --env CERT_PASSWORD=<CERT_PASSWORD> --env CERT_FILE=<CERT_FILE> --env NODE_OPTIONS=<NODE_OPTIONS> --env MCP_PORT=<MCP_PORT> --env STORAGE_PATH=<STORAGE_PATH> --transport stdio mcp-nfse-nacional -- npx -y mcp-nfse-nacionalWhat mcp-nfse-nacional does
mcp-nfse-nacional connects an AI agent to the national NFSe portal. It searches issued invoices within a date range and returns each record’s date, recipient, amount, status, and key. A key can then be used to fetch full invoice data, save its XML, or download a DANFSe PDF.
The server exposes three MCP tools: nfse_buscar, nfse_detalhes, and nfse_pdf. Login happens on the first call, with another attempt after an expired session. It runs through npx with either stdio or streamable-http; downloaded files are stored under ./storage by default.
A digital certificate file in .pfx or .p12 format and its password must be supplied through CERT_FILE and CERT_PASSWORD. The streamable-http mode has no built-in authentication, so exposing it publicly requires an authenticated reverse proxy or equivalent protection.
What it helps with
- search issued NFSe within a date range
- inspect an invoice using its key
- save NFSe XML to local storage
- download a DANFSe PDF
- let an AI agent query NFSe records
Example prompts for the agent
- Find issued NFSe between
YYYY-MM-DDandYYYY-MM-DD. - Retrieve the full NFSe record for its key and save the XML locally.
- Download the DANFSe PDF for the NFSe with the given key.
How to install mcp-nfse-nacional
Platform CLI
claude mcp add --env CERT_PASSWORD=<CERT_PASSWORD> --env CERT_FILE=<CERT_FILE> --env NODE_OPTIONS=<NODE_OPTIONS> --env MCP_PORT=<MCP_PORT> --env STORAGE_PATH=<STORAGE_PATH> --transport stdio mcp-nfse-nacional -- npx -y mcp-nfse-nacionalReplace <…> with your own values
Platform CLI
codex mcp add mcp-nfse-nacional --env CERT_PASSWORD=<CERT_PASSWORD> --env CERT_FILE=<CERT_FILE> --env NODE_OPTIONS=<NODE_OPTIONS> --env MCP_PORT=<MCP_PORT> --env STORAGE_PATH=<STORAGE_PATH> -- npx -y mcp-nfse-nacionalReplace <…> with your own values
Config file
{
"mcpServers": {
"mcp-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>"
}
}
}
}Replace <…> with your own values
Config file
{
"servers": {
"mcp-nfse-nacional": {
"type": "stdio",
"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>"
}
}
}
}Replace <…> with your own values
Platform CLI
gemini mcp add -e CERT_PASSWORD=<CERT_PASSWORD> -e CERT_FILE=<CERT_FILE> -e NODE_OPTIONS=<NODE_OPTIONS> -e MCP_PORT=<MCP_PORT> -e STORAGE_PATH=<STORAGE_PATH> mcp-nfse-nacional npx -y mcp-nfse-nacionalReplace <…> with your own values
Step by step, with commands for each platform: How to add an MCP server to Claude Code, Codex, Cursor, VS Code, Gemini CLI and more
Questions about mcp-nfse-nacional
How do I install mcp-nfse-nacional in Claude Code?
Run claude mcp add mcp-nfse-nacional -e CERT_PASSWORD=<CERT_PASSWORD> -e CERT_FILE=<CERT_FILE> -- npx -y mcp-nfse-nacional.
What does mcp-nfse-nacional do?
It searches issued NFSe by date range, retrieves invoice details by key, stores XML files, and downloads DANFSe PDFs through MCP tools.
What is required for the server to work?
You need a .pfx or .p12 digital certificate, its password, and the CERT_FILE and CERT_PASSWORD environment variables. The HTTP mode has no built-in authentication, so protect it before exposing it beyond the local host.
