samuelmoraesf/mcp-nfse-nacional

By samuelmoraesf

•Updated 7 months ago

MCP para consultar NFSe no portal nacional. Busque notas, baixe XMLs e PDFs direto do seu AI agent

Image

Integration & delivery

Machine learning & AI

10K+

Overview Tags

samuelmoraesf/mcp-nfse-nacional repository overview

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

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

Tag summary

Recent tags

Content type

Image

Digest

sha256:0327758bb…

Size

66.2 MB

Last updated

7 months ago

docker pull samuelmoraesf/mcp-nfse-nacional