Skip to main content
Glama
mcp-nfse-nacional

mcp-nfse-nacional

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

nfse_buscar

Busca 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_detalhes

Obté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_pdf

Baixa 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.

Related MCP server: brasilnfe-mcp

Variáveis de ambiente

Variável

Obrigatória

Padrão

Descrição

CERT_FILE

Sim

—

Caminho para o arquivo do certificado digital (.pfx / .p12), relativo ao diretório do projeto ou absoluto.

CERT_PASSWORD

Sim

—

Senha do certificado digital.

MCP_TRANSPORT

Não

stdio

Modo de transporte do servidor MCP. Valores aceitos: stdio ou streamable-http.

MCP_HOST

Não

127.0.0.1

Endereço de bind do servidor HTTP (somente no modo streamable-http).

MCP_PORT

Não

3000

Porta do servidor HTTP (somente no modo streamable-http).

STORAGE_PATH

Não

./storage

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-nacional

Exemplo 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-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):

{
  "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-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.

Available Tools

3 tools
nfse_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

    A4/5.0

    Scored across 3 tools

    Disambiguation5/5

    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.

    Naming Consistency4/5

    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.

    Tool Count4/5

    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.

    Completeness4/5

    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

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      B
      maintenance
      MCP server that lets AI agents issue Brazilian NFS-e service invoices via Focus NFe, with tools for creating, querying, and canceling invoices.
      MIT
    • F
      license
      Not graded
      quality
      D
      maintenance
      MCP 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.
      -
    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables consulting Brazilian electronic invoices (NFE) from official Receita Federal sources through a read-only MCP tool.
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      MCP 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