fiscal-mcp

Documento fiscal brasileiro como ferramenta de agente. Valide NF-e e NFS-e antes de transmitir — sem certificado, sem cadastro, sem enviar nada para lugar nenhum.

pip install fiscal-mcp
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)

Por que existe

Rejeição da SEFAZ chega tarde, custa uma transmissão e vem com mensagem críptica. Boa parte dos motivos é aritmética simples ou campo fora de formato — coisa que dá para pegar antes de enviar, na sua própria máquina.

E agora tem prazo: desde 3 de agosto de 2026, documentos fiscais do regime regular precisam trazer os campos de IBS e CBS, e notas sem eles podem ser rejeitadas (CGIBS).

Enquanto isso, um agente de IA consegue mexer no seu Notion e no seu GitHub, mas não sabe ler uma nota fiscal.

O que ele faz

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.

Como usar

Na linha de comando

fiscal-mcp validar nota.xml          # NF-e ou NFS-e, ele descobre sozinho
fiscal-mcp validar nota.xml --json   # para script e CI
fiscal-mcp explicar nota.xml         # resumo estruturado
fiscal-mcp chave 4326081234...       # 44 dígitos (NF-e) ou 50 (NFS-e)
fiscal-mcp rejeicao 539              # traduz o código da SEFAZ
fiscal-mcp rejeicao                  # lista o catálogo

Sai com código 1 quando encontra erro, então serve direto em CI.

Como servidor MCP

pip install "fiscal-mcp[servidor]"

{
  "mcpServers": {
    "fiscal": { "command": "fiscal-mcp-servidor" }
  }
}

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

O que ele não faz

Escrito antes das perguntas, porque prometer demais é o jeito mais rápido de perder a confiança de quem trabalha com fiscal:

• Não emite, não assina, não transmite. Sem certificado digital envolvido.
• Passar aqui não garante autorização. É validação local: pega o erro previsível, não substitui a SEFAZ nem o XSD oficial.
• NFS-e só no padrão nacional. Município com padrão próprio não é reconhecido (ADR-0006).
• Não verifica dígito verificador de NFS-e — o algoritmo não foi confirmado, e chutar produziria acusação falsa.
• Não valida assinatura digital.
• Não dá conselho tributário. CFOP, CST e alíquota são do seu contador.

Estado da validação, por documento

A regra de IBS/CBS está marcada como pendente_confirmacao e só emite aviso: o leiaute exato ainda não foi conferido contra a nota técnica oficial. Acusar errado é pior que não acusar.

Tem um XML real que pode compartilhar? É a contribuição mais valiosa possível agora — abra uma issue com os dados trocados por fictícios.

Escrever uma regra

Regras são dados, não código. Absorver uma nota técnica deveria ser editar um YAML — e é:

- id: tot-produtos-confere
  tipo: soma_itens
  severidade: erro          # erro | aviso | informacao
  campo_item: prod/vProd
  campo_total: total/ICMSTot/vProd
  tolerancia: "0.01"
  mensagem: O total de produtos não bate com a soma dos itens
  acao: >
    Some o vProd de cada item e compare com total/ICMSTot/vProd.

Tipos disponíveis: existe, nao_vazio, valor_em, formato, soma_itens, condicional.

Todo achado precisa de acao. Quem lê é um agente que vai tentar de novo — erro sem ação vira loop de retry ou nota duplicada. Um teste falha se alguma regra não tiver.

Contribuir

O que mais ajuda, em ordem:

1. XML real anonimizado — principalmente NF-e, e municípios de NFS-e diferentes.
2. Código de rejeição que você levou e não está no catálogo.
3. Regra nova em regras/, com teste.
4. Confirmação do leiaute de IBS/CBS contra a nota técnica oficial.

Como isso vai crescer

Este projeto é a fatia zero de algo maior: servidores MCP mantidos para o fiscal brasileiro, incluindo emissão. O que vem depois, e por que nesta ordem, está escrito:

Duas decisões que explicam o resto:

• ADR-0008 — não escrevo integração com SEFAZ antes de saber que existe quem pague pela manutenção.
• ADR-0005 — certificado digital de cliente não passa pela minha infra. O A1 é a identidade jurídica da empresa.

Licença

MIT — código e regras.

Feito por José Torquato, que também mantém o Cilada.