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:

> 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

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.