Skip to main content
Glama
SamuelMoraesF

mcp-nfse-nacional

by SamuelMoraesF
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Hybrid

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.

ParametersJSON Schema
NameRequiredDescriptionDefault
data_fimYesData de fim no formato YYYY-MM-DD
data_inicioYesData de início no formato YYYY-MM-DD

TDQS

A3.8/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full transparency burden. It discloses return fields (date, recipient, value, status, key) but does not mention permissions, pagination, ordering, or side effects. Adequate for a simple read operation but not comprehensive.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single sentence, efficient, and front-loaded with the verb and resource. It contains no wasted words and is easy to parse.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple two-parameter search tool without an output schema, the description adequately lists the return fields. It lacks details on pagination or ordering but is sufficient given the tool's simplicity.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% with both parameters clearly documented as date strings with format. The description itself adds no additional parameter semantics beyond the schema, so the baseline score of 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses the specific verb 'Busca' (search) and identifies the resource (NFSe) and the period filter, clearly distinguishing it from sibling tools like nfse_detalhes and nfse_pdf.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage for searching NFSe by date range, but does not explicitly state when to use this tool versus alternatives or provide exclusions. It is adequate but lacks explicit guidance.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

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.

ParametersJSON Schema
NameRequiredDescriptionDefault
chaveYesChave identificadora da NFSe

TDQS

A4/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description must disclose side effects and context. It reveals a significant side effect: 'salva o XML localmente' (saves the XML locally). It also lists return data. However, it lacks deeper context such as authorization requirements, failure modes, or the format/path of the saved XML. Thus, it provides basic but not exhaustive transparency.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two short sentences that are entirely informative: first states the main purpose, second lists return data and the side effect. No filler or repetition.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The tool is simple with one parameter and no output schema. The description covers the main function, the specific return elements, and the local XML saving side effect. It lacks only minor details (e.g., where the XML is saved, whether it returns anything beyond a confirmation), but overall it is sufficiently complete for invocation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, as the 'chave' parameter already has a description ('Chave identificadora da NFSe'). The tool description redundantly mentions 'a partir de sua chave' but adds no new semantic detail about the key's format or constraints. Baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses the specific verb 'Obtém' (gets) with the resource 'detalhes completos de uma NFSe específica' and specifies the input source 'a partir de sua chave'. It also lists the returned data categories (cabeçalho, emitente, valores, DPS), clearly distinguishing it from sibling tools like nfse_buscar (search) and nfse_pdf (PDF generation).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description clearly indicates when to use the tool: when you have a specific NFSe key and need complete details. It provides context without explicitly naming alternatives or exclusions, but the sibling tools imply differentiation. Given the clear context, it earns a 4.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

nfse_pdfA

Baixa o PDF (DANFSe) de uma NFSe específica a partir de sua chave. Retorna o caminho do arquivo PDF salvo localmente.

ParametersJSON Schema
NameRequiredDescriptionDefault
chaveYesChave identificadora da NFSe

TDQS

A4/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full burden. It discloses the key behavioral trait that the PDF is saved locally and returns the file path ('Retorna o caminho do arquivo PDF salvo localmente'). It stops short of disclosing error handling, file overwrite behavior, or permission requirements, but the primary side effect is clearly stated.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, front-loaded sentence starting with the verb 'Baixa'. It provides essential information with no filler or redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple one-parameter tool with no output schema and no annotations, the description sufficiently explains what it does and what it returns. It could mention that the key must belong to an existing NFSe (obtained via sibling tools), but this is implied by the purpose and not a major gap.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% (the only parameter 'chave' is described as 'Chave identificadora da NFSe'). The description adds no extra meaning beyond restating that the download is 'a partir de sua chave'. Baseline of 3 applies as the schema already documents the parameter.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool downloads the PDF (DANFSe) of a specific NFSe using its key, with a specific verb ('Baixa') and resource. This distinguishes it from siblings 'nfse_buscar' (search) and 'nfse_detalhes' (details).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage via the action (download PDF from a given key) but does not explicitly state when to use it versus siblings or any exclusions. There is no guidance like 'use nfse_buscar to find the key first' or 'this is the only tool that returns a local file path.'

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 3 tool updatesv1.0.3
    • First observednfse_buscar
    • First observednfse_detalhes
    • First observednfse_pdf
Deploy Server
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

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 issues

Resources

Related MCP Connectors

Related MCP Servers

  • brazil-invoice-mcp

    junter1989k-ai
    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
  • brasilnfe-mcp by BrasilNFe

    brasilnfe-mcpofficial

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

  • Receita Federal: NFE

    mcp-dir
    A
    license
    Not graded
    quality
    C
    maintenance
    Enables consulting Brazilian electronic invoices (NFE) from official Receita Federal sources through a read-only MCP tool.
    MIT

  • Receita Federal NFS-e - Notas

    mcp-dir
    A
    license
    Not graded
    quality
    C
    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