fiscal-mcp

// documento fiscal como ferramenta de agente

Descubra o erro na sua nota
antes da SEFAZ descobrir.

Rejeição chega tarde, custa uma transmissão e vem com mensagem críptica. Boa parte dos motivos é aritmética simples ou campo fora de formato — dá para pegar antes, na sua máquina. Sem certificado, sem cadastro, sem enviar nada para lugar nenhum.

Instalar → Ver o código
01.

Dois comandos

# instala
pip install fiscal-mcp

# valida — NF-e ou NFS-e, ele descobre sozinho
fiscal-mcp validar nota.xml

  [erro] tot-produtos-confere
      O total de produtos não bate com a soma dos itens
      soma dos itens = 250.00, total/ICMSTot/vProd = 999.00, diferença de 749.00
      → Some o vProd de cada item e compare com total/ICMSTot/vProd.

  [aviso] ibs-cbs-grupo-totais-presente
      Grupo de totais de IBS/CBS não encontrado
      → Obrigatório desde 03/08/2026 para o regime regular.

  1 erro(s), 1 aviso(s)

Sai com código 1 quando encontra erro, então serve direto no seu CI. E como servidor MCP, o agente passa a conseguir ler nota fiscal:

pip install "fiscal-mcp[servidor]"

// no cliente MCP
{ "mcpServers": { "fiscal": { "command": "fiscal-mcp-servidor" } } }

Aí é só perguntar: "esse XML está pronto para transmitir?"

02.

O que ele faz — e o que não faz

ferramentao que faz
validar_nfeestrutura, coerência dos totais, formato e chave — com o que fazer em cada achado
validar_nfseNFS-e do padrão nacional: estrutura, DPS embutida, prestador, serviço
explicar_nfe
explicar_nfse		resumo estruturado, em vez do XML inteiro estourando o contexto
explicar_rejeicaocódigo da SEFAZ → significado → ação, e se é reversível
validar_chave_acesso
validar_chave_nfse		decompõe 44 ou 50 dígitos e confere o que dá para conferir

Nenhuma delas assina, transmite, emite ou cancela documento. Não existe caminho, nesta versão, para causar efeito fiscal — e um teste verifica isso a cada mudança.

Estado da validação, sem maquiagem

  • NFS-e nacional — 10 regras, testado contra uma nota autorizada de verdade.
  • NF-e / NFC-e — 12 regras, mas testado apenas contra XML sintético. Ainda não passou por uma nota real.
  • A regra de IBS/CBS emite só aviso: o leiaute exato ainda não foi conferido contra a nota técnica oficial. Acusar errado é pior que não acusar.
  • Passar aqui não garante autorização. É validação local — pega o erro previsível, não substitui a SEFAZ.
  • NFS-e cobre só o padrão nacional. Município com padrão próprio não é reconhecido.
03.

Como você pode ajudar

O buraco maior é conhecido e está escrito acima: a NF-e nunca foi testada contra uma nota real. Isso não se resolve escrevendo mais código — se resolve com documento de verdade na mão.

  • XML real anonimizado — principalmente NF-e, e municípios de NFS-e diferentes. É a contribuição mais valiosa que existe agora.
  • Código de rejeição que você levou e não está no catálogo.
  • Confirmação do leiaute de IBS/CBS contra a nota técnica oficial.

Regras são dados, não código: absorver uma nota técnica é editar um YAML. Contribuir não exige entender o projeto inteiro — só conhecer o golpe que a SEFAZ aplicou em você.

// e se você mantém integração fiscal

Quanto do seu ano foi para isso?

Estou conversando com quem mantém integração fiscal para entender onde dói mais — nota técnica, homologação, cobertura municipal. Se você vive isso, quero ouvir. São 15 minutos e não é pitch.

Falar comigo →