NFSe National

Interacts with NFSe portal to search, retrieve details, and download PDFs using MCP with certificate-based authentication.

javascript

0

GitHub Stars

javascript

Language

4 months ago

First Indexed

2 months ago

Catalog Refreshed

Documentation & install

Readme and setup notes from the catalogue, plus a client-ready config you can copy for your MCP host.

Installation

Add the following to your MCP client configuration file.

Configuration

View docs

You can run the NFSe national MCP server to query electronic service invoices from nfse.gov.br, authenticate with a digital certificate, and fetch details and PDFs of NFSe documents. The server supports local operation via standard MCP protocol and can expose an HTTP endpoint for listening clients. This guide shows practical steps to install, run, and use the server with MCP clients.

How to use

You will connect to the MCP server using an MCP client. Choose the transport mode based on your environment. In stdio mode, your client communicates directly with the local process started via npx. In streamable HTTP mode, the server runs as a background service and exposes an HTTP endpoint that MCP clients can query.

How to install

Prerequisites: you need Node.js and npm or yarn installed if you plan to run via npx. You also need access to your digital certificate (.pfx/.p12) and its password.

Choose one of the available run modes and follow the corresponding steps.

Additional sections

Configuration, security, and usage details are provided below to help you operate safely and reliably.

Tools exposed by the MCP server include the following actions: nfse_buscar to search NFSe within a date range, nfse_detalhes to fetch complete details for a specific NFSe by its key and save the XML locally, and nfse_pdf to download the DANFSe PDF for a given NFSe key and save it locally.

Environment variables control certificate handling and server behavior. The required variables are CERT_FILE and CERT_PASSWORD. Optional variables include MCP_TRANSPORT, MCP_HOST, MCP_PORT, and STORAGE_PATH. You will configure these in a .env file or your environment before starting the server.

Available tools

nfse_buscar

Search NFSe issued within a date range and return a list with date, recipient, value, status, and the key for each note.

nfse_detalhes

Retrieve complete details of an NFSe by its key, including header, issuer, values, DPS, and save the XML locally.

nfse_pdf

Download the PDF (DANFSe) of an NFSe by its key and save the PDF locally.