mcp-nfse-nacional
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@mcp-nfse-nacional buscar NFSe emitidas em janeiro de 2025"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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:
Ferramenta | Descrição | Parâmetros |
| Busca NFSe emitidas em um período. Retorna lista com data, destinatário, valor, status e chave de cada nota. |
|
| Obtém os detalhes completos de uma NFSe a partir da sua chave. Retorna cabeçalho, emitente, valores, DPS e salva o XML localmente. |
|
| Baixa o PDF (DANFSe) de uma NFSe a partir da sua chave. Retorna o caminho do arquivo PDF salvo localmente. |
|
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.
Related MCP server: brasilnfe-mcp
Variáveis de ambiente
Variável | Obrigatória | Padrão | Descrição |
| Sim | — | Caminho para o arquivo do certificado digital ( |
| Sim | — | Senha do certificado digital. |
| Não |
| Modo de transporte do servidor MCP. Valores aceitos: |
| Não |
| Endereço de bind do servidor HTTP (somente no modo |
| Não |
| Porta do servidor HTTP (somente no modo |
| Não |
| Diretó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.):
CERT_FILE=./certificado.pfx CERT_PASSWORD=sua_senha npx -y mcp-nfse-nacionalExemplo de configuração em um cliente MCP (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 Streamable HTTP
Ideal para ambientes onde o servidor precisa ficar escutando conexões 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-nacionalO endpoint MCP ficará disponível em http://127.0.0.1:3000/mcp.
Exemplo de configuração em um cliente MCP (mcp.json):
{
"servers": {
"nfse-nacional": {
"type": "streamable-http",
"url": "http://127.0.0.1:3000/mcp"
}
}
}Executando via Docker (Streamable HTTP)
Build da imagem
docker build -t mcp-nfse-nacional .Execução
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-nacionalO endpoint MCP ficará disponível em http://localhost:3000/mcp.
O Dockerfile já define
MCP_TRANSPORT=streamable-http,MCP_HOST=0.0.0.0eMCP_PORT=3000por 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,*.p12e.envao 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 em127.0.0.1ou 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.
Available Tools
3 toolsnfse_buscarA
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.
Inputs: data_fim (required), data_inicio (required).
nfse_detalhesA
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.
Inputs: chave (required).
nfse_pdfA
Baixa o PDF (DANFSe) de uma NFSe específica a partir de sua chave. Retorna o caminho do arquivo PDF salvo localmente.
Inputs: chave (required).
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 3 tools
Each tool has a distinct purpose: nfse_buscar searches for invoices in a period, nfse_detalhes retrieves full details for a specific invoice, and nfse_pdf downloads the PDF. There is no overlap or ambiguity between them.
All tools share the 'nfse_' prefix, but the second part mixes a verb (buscar) with nouns (detalhes, pdf). This is a minor deviation from a strict verb_noun pattern, though the prefix provides consistency and readability.
With 3 tools, the server is minimal but well-scoped for a focused NFSe consultation/download workflow. It is not too thin for the apparent purpose, and each tool adds clear value.
The set covers the core operations for retrieving NFSe documents: search, detail retrieval, and PDF download. Missing actions like emission or cancellation are outside the apparent consumer-focused scope, so no critical gaps exist.
Maintenance
Related MCP Connectors
Brazilian fiscal MCP server - issue NF-e, NFC-e, NFS-e, CT-e, MDF-e and DC-e via SEFAZ.
Brazil NFS-e service invoices for AI agents via Focus NFe and NFe.io. Stateless, never stores data.
Issue Brazilian service invoices (NFS-e Nacional) from your AI, with preview and confirmation.
Brazilian SEFAZ e-invoices (NF-e, CT-e) issued against your company. A1 cert, DANFE PDF.
Related MCP Servers
- AlicenseNot gradedqualityBmaintenanceMCP server that lets AI agents issue Brazilian NFS-e service invoices via Focus NFe, with tools for creating, querying, and canceling invoices.MIT

brasilnfe-mcpofficial
FlicenseNot gradedqualityDmaintenanceMCP server that exposes Brazilian tax infrastructure as tools, resources, and prompts, enabling AI agents to emit and manage fiscal documents (NF-e, NFC-e, NFS-e, CT-e, MDF-e, DC-e) through natural language.-- AlicenseNot gradedqualityDmaintenanceEnables consulting Brazilian electronic invoices (NFE) from official Receita Federal sources through a read-only MCP tool.MIT
- AlicenseNot gradedqualityDmaintenanceMCP server to query details of received electronic service invoices (NFS-e) from the Brazilian Federal Revenue. Read-only, no credentials required, pay-per-use with prepaid credits.MIT