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 versão no PyPI
01.

Dois comandos

# instala, com a validação por schema XSD oficial
pip install "fiscal-mcp[xsd]"

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

  [erro] ibs-cclasstrib-prefixo-cst
      cClassTrib não corresponde ao CST do item
      item 2: imposto/IBSCBS/cClassTrib = '000123' não começa por
              imposto/IBSCBS/CST = '200'
      → Os três primeiros dígitos do cClassTrib são o CST do item.
        É o erro mais comum ao ligar o módulo de IBS/CBS num ERP.

  [erro] schema-elemento-fora-de-ordem
      cEAN apareceu onde o leiaute espera xProd
      item 1, linha 62 do XML
      → O schema da NF-e exige a sequência exata do leiaute —
        trocar a ordem reprova mesmo com todos os campos presentes.

  2 erro(s), 0 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,xsd]"

// 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_nfeschema XSD oficial, regras fiscais (IBS/CBS incluso), totais 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 — schema XSD oficial + 28 regras, das quais 17 são de IBS/CBS, conferidas contra a tabela oficial da SVRS embarcada no repositório com sha256. Validado contra duas NF-e reais autorizadas em produção: a que traz o grupo IBS/CBS passou com zero achados; a anterior à reforma passou com zero erros e o aviso correto. Ainda não cobre nota real com monofasia, redução de alíquota ou crédito presumido — esses caminhos só foram testados contra fixture.
  • A regra de grupo IBS/CBS ausente emite só aviso: a NT 2025.002 v1.51 reclassificou a rejeição correspondente como implementação futura, então a nota não é recusada por isso hoje. Acusar errado é pior que não acusar.
  • A validação por schema exige o extra [xsd]. Sem ele, o laudo diz que essa camada não rodou — nunca finge que rodou.
  • 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. Cada código do catálogo já tem página com XML errado e corrigido.
  • Leitura da seção 7 da NT 2025.002-RTC v1.51 — o leiaute já está mapeado; o que falta confirmar em fonte primária são os códigos de rejeição, e nenhum entra aqui sem leitura humana.

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 →