Mcp Nfse Nacional

io.github.SamuelMoraesFPublished by GitHub account SamuelMoraesFv1.0.3Updated Oct 27, 2026

MCP Server para consulta de NFSe no portal nacional (nfse.gov.br)

VerifiedSTDIODesktop onlyFinanceBusiness & Commerce

Overview

AI-generated overview

MCP server that logs into Brazil's national NFSe portal with a digital certificate so an assistant can search, detail and download service invoices.

What you can do
  • Search issued NFSe for a date range, returning date, recipient, amount, status and key for each note
  • Fetch full details of one NFSe by key, including header, issuer, amounts and DPS, and save the XML locally
  • Download the DANFSe PDF for a given key and return the local file path
  • Authenticate automatically with the digital certificate, retrying login when the session expires
When to use it
Useful when you work with Brazilian service invoices (NFSe) and want an assistant to look up issued notes for a period, inspect a specific note, or collect its XML and PDF without navigating the national portal by hand.
Requirements
Runs locally via npx (Node.js) or Docker. Requires a digital e-CNPJ/e-CPF certificate file (.pfx/.p12) set in CERT_FILE and its password in CERT_PASSWORD. Optional MCP_TRANSPORT, MCP_HOST, MCP_PORT and STORAGE_PATH control transport and where XMLs/PDFs are saved. Network access to nfse.gov.br is needed.
Before you install
The certificate is a legally binding identity asset; never commit it or its password, and restrict file permissions. The HTTP mode has no authentication of its own, so do not expose it publicly. Prefer environment variables or a secrets manager over command-line arguments for CERT_PASSWORD. Downloaded XMLs and PDFs contain fiscal data stored in STORAGE_PATH and need appropriate protection.

Installation

In SourceWeft

  1. Open Mcp Nfse Nacional in the dashboard and add it to a workspace.
  2. Enable the server for the chats that should use its tools.

Desktop only via STDIO. STDIO servers start a local process, so they need the SourceWeft desktop host.

Other MCP clients

Follow the launch instructions in the repository.

README

mcp-nfse-nacional

MCP Server para consulta de Notas Fiscais de Serviço Eletrônicas (NFSe) no portal nacional (nfse.gov.br). Permite que agentes de IA autentiquem-se com certificado digital e-CNPJ/e-CPF e consultem, detalhem e baixem PDFs de NFSe emitidas.

Ferramentas disponíveis

O servidor expõe três ferramentas via protocolo MCP:

FerramentaDescriçãoParâmetros
nfse_buscarBusca NFSe emitidas em um período. Retorna lista com data, destinatário, valor, status e chave de cada nota.data_inicio (YYYY-MM-DD), data_fim (YYYY-MM-DD)
nfse_detalhesObtém os detalhes completos de uma NFSe a partir da sua chave. Retorna cabeçalho, emitente, valores, DPS e salva o XML localmente.chave (string)
nfse_pdfBaixa o PDF (DANFSe) de uma NFSe a partir da sua chave. Retorna o caminho do arquivo PDF salvo localmente.chave (string)

A autenticação é gerenciada automaticamente. O login é realizado na primeira chamada e, caso a sessão expire (erro de autenticação), uma nova tentativa de login é feita de forma transparente.

Variáveis de ambiente

VariávelObrigatóriaPadrãoDescrição
CERT_FILESim—Caminho para o arquivo do certificado digital (.pfx / .p12), relativo ao diretório do projeto ou absoluto.
CERT_PASSWORDSim—Senha do certificado digital.
MCP_TRANSPORTNãostdioModo de transporte do servidor MCP. Valores aceitos: stdio ou streamable-http.
MCP_HOSTNão127.0.0.1Endereço de bind do servidor HTTP (somente no modo streamable-http).
MCP_PORTNão3000Porta do servidor HTTP (somente no modo streamable-http).
STORAGE_PATHNão./storageDiretório onde os XMLs e PDFs baixados serão armazenados.

Você pode definir as variáveis em um arquivo .env na raiz do projeto.

Executando via npx

Modo stdio (padrão)

Ideal para integração direta com clientes MCP (Claude Desktop, VS Code, etc.):

bash
CERT_FILE=./certificado.pfx CERT_PASSWORD=sua_senha npx -y mcp-nfse-nacional

Exemplo de configuração em um cliente MCP (mcp.json):

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 Streamable HTTP

Ideal para ambientes onde o servidor precisa ficar escutando conexões HTTP:

bash
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

O endpoint MCP ficará disponível em http://127.0.0.1:3000/mcp.

Exemplo de configuração em um cliente MCP (mcp.json):

json
{  "servers": {    "nfse-nacional": {      "type": "streamable-http",      "url": "http://127.0.0.1:3000/mcp"    }  }}

Executando via Docker (Streamable HTTP)

Build da imagem

bash
docker build -t mcp-nfse-nacional .

Execução

bash
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

O endpoint MCP ficará disponível em http://localhost:3000/mcp.

O Dockerfile já define MCP_TRANSPORT=streamable-http, MCP_HOST=0.0.0.0 e MCP_PORT=3000 por padrão.

Segurança

⚠️ O certificado digital é um ativo crítico. Ele possui validade jurídica e representa a identidade da sua empresa ou pessoa física perante a Receita Federal e demais órgãos. Trate-o com o mesmo cuidado que trataria uma senha-mestre.

Orientações essenciais

  • Nunca versione o certificado (.pfx / .p12) ou sua senha em repositórios Git. Adicione *.pfx, *.p12 e .env ao seu .gitignore.
  • Não exponha o servidor HTTP publicamente. No modo streamable-http, o servidor não possui autenticação própria. Mantenha-o acessível apenas em 127.0.0.1 ou proteja-o com um reverse proxy autenticado (com mTLS, API key, etc.).
  • Use variáveis de ambiente ou secrets managers para fornecer a senha do certificado. Evite passá-la como argumento de linha de comando, pois ela pode ficar visível no histórico do shell e na listagem de processos (ps).
  • Monte o certificado como somente leitura no Docker (flag :ro), minimizando riscos de alteração acidental.
  • Restrinja permissões do arquivo do certificado no sistema de arquivos (chmod 400 certificado.pfx).
  • Monitore a expiração do certificado. Certificados digitais possuem validade (geralmente 1 a 3 anos). Tenha um processo para renovação.
  • Armazenamento local de XMLs e PDFs: os arquivos baixados são salvos no diretório storage/. Garanta que esse diretório tenha permissões adequadas e que os dados fiscais sejam tratados conforme as políticas de privacidade da sua organização.

Source: README.md at commit 16fe555

Tools

0
SourceWeft has not started this package in its sandbox yet, so its tools are not known.

Version history

1
  1. v1.0.3LatestSep 16, 2026

Score

40% of the applicable checks met

How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.

  • Reached in the last 30 days25 pts

    Keep the endpoint answering the MCP handshake; SourceWeft probes it every 30 days.

  • Auth declared10 pts

    Declare the credential headers in the registry entry, or keep the endpoint answering the probe so its auth can be classified.

  • Tools listed15 pts

    Answer tools/list without a credential, or ship a package that starts in a sandbox without one.

  • DescriptionRequired15 pts
  • Logo10 pts
  • Documentation15 pts
  • License10 pts

    Declare a license in the repository or the registry entry.