nfse_buscar
Busca notas fiscais de serviço eletrônicas (NFSe) emitidas em um período. Retorna lista com data, destinatário, valor, status e chave de cada nota.
LABSCO SUMMARY
Invoice lookup that ends with the XML and the PDF already on disk.
The three tools chain in one direction: search a period, take an access key out of the result, then pull the full record or the DANFSe. Because nfse_detalhes and nfse_pdf write files and return paths, the model keeps a short answer while the artefacts land where the accounting work happens. Issuing or cancelling an invoice is not in the tool set — this side is retrieval only.
What it is
A retrieval server for Brazil's national NFSe service, where every invoice is addressed by its access key.
What you get
- Search NFSe issued between a start and an end date, and get the date, recipient, value, status and access key of each one.
- Open a single invoice from its access key: header, issuer, values and DPS, with the XML written to disk.
- Download the DANFSe PDF for an invoice and receive the path of the saved file.
Requirements
A digital certificate (e-CNPJ or e-CPF) as a .pfx or .p12 file: its path goes in CERT_FILE and its password in CERT_PASSWORD. nfse_detalhes saves the XML and nfse_pdf saves the PDF locally, in ./storage unless STORAGE_PATH points elsewhere, and both hand back a path rather than the document itself.
Setup effort
One command plus credentials — CERT_FILE=<YOUR_CERT_FILE> CERT_PASSWORD=<YOUR_CERT_PASSWORD> npx -y mcp-nfse-nacional
USE CASES
01
Reconciling a month of service invoices
Ask for everything issued between two dates, then walk the access keys that come back and pull each full record with its XML.
02
Producing the DANFSe a client has asked for
Find the invoice by the period it was issued in, then fetch its PDF and hand over the file path.
3 tools
Counted once with only startup setup. Other versions, modes or optional credentials may expose a different list.
nfse_detalhes
Obtém os detalhes completos de uma NFSe específica a partir de sua chave. Retorna dados do cabeçalho, emitente, valores, DPS e salva o XML localmente.
nfse_pdf
Baixa o PDF (DANFSe) de uma NFSe específica a partir de sua chave. Retorna o caminho do arquivo PDF salvo localmente.
BEFORE YOU INSTALL
What to know first
Tools you get
3 tools when we connected. It lists, fetches and downloads invoices only; nothing issues, corrects or cancels one. nfse_detalhes writes the XML to disk, and login happens automatically on the first call.
Requires
- npx on PATH
- CERT_FILE in your environment
- CERT_PASSWORD in your environment
CONTEXT COST
Light Standing cost
Rated by the size of the 3 tool definitions that ride along on every turn, not by how many there are
INSTALLATION
Connect your client
Server setup
TERMINAL
CERT_FILE=<YOUR_CERT_FILE> CERT_PASSWORD=<YOUR_CERT_PASSWORD> npx -y mcp-nfse-nacionalMCP Clients
Claude Desktop, Other MCP clients
JSON
{
"mcpServers": {
"nfse-nacional": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"mcp-nfse-nacional"
],
"env": {
"CERT_FILE": "<YOUR_CERT_FILE>",
"CERT_PASSWORD": "<YOUR_CERT_PASSWORD>"
}
}
}
}<YOUR_CERT_FILE> is the full path to your e-CNPJ or e-CPF digital certificate (.pfx or .p12), and <YOUR_CERT_PASSWORD> is that certificate's password.
VS Code
VS CODE · JSON
{
"servers": {
"nfse-nacional": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"mcp-nfse-nacional"
],
"env": {
"CERT_FILE": "<YOUR_CERT_FILE>",
"CERT_PASSWORD": "<YOUR_CERT_PASSWORD>"
}
}
}
}<YOUR_CERT_FILE> is the full path to your e-CNPJ or e-CPF digital certificate (.pfx or .p12), and <YOUR_CERT_PASSWORD> is that certificate's password.
Any MCP client — HTTP
Start the server in Streamable HTTP mode:
ANY MCP CLIENT — HTTP · TERMINAL
CERT_FILE=<YOUR_CERT_FILE> CERT_PASSWORD=<YOUR_CERT_PASSWORD> MCP_TRANSPORT=streamable-http MCP_HOST=127.0.0.1 MCP_PORT=3000 npx -y mcp-nfse-nacionalThen point your client at the endpoint it opens:
ANY MCP CLIENT — HTTP · JSON
{
"mcpServers": {
"nfse-nacional": {
"type": "streamable-http",
"url": "http://127.0.0.1:3000/mcp"
}
}
}Clients spell the "type" value differently: Claude Code and VS Code use "http", Cline uses "streamableHttp", and Roo Code uses "streamable-http". Claude Desktop does not accept a URL entry in its config file.
Any MCP client — Docker
ANY MCP CLIENT — DOCKER · TERMINAL
git clone https://github.com/SamuelMoraesF/mcp-nfse-nacional
cd mcp-nfse-nacional
docker build -t mcp-nfse-nacional .
docker run -d --name mcp-nfse-nacional -p 3000:3000 -v <YOUR_PATH_TO_CERTIFICATE>:/app/certificado.pfx:ro -v <YOUR_PATH_TO_STORAGE>:/app/storage -e CERT_FILE=certificado.pfx -e CERT_PASSWORD=<YOUR_CERT_PASSWORD> mcp-nfse-nacional
<YOUR_PATH_TO_STORAGE> is the folder where the XMLs and PDFs should land. Then point your client at the endpoint:ANY MCP CLIENT — DOCKER · JSON
{
"mcpServers": {
"nfse-nacional": {
"type": "streamable-http",
"url": "http://localhost:3000/mcp"
}
}
}Clients spell the "type" value differently: Claude Code and VS Code use "http", Cline uses "streamableHttp", and Roo Code uses "streamable-http". Claude Desktop does not accept a URL entry in its config file.
