Skip to main content
Glama
mcp-fiscal-brasil

mcp-fiscal-brasil

by DeHor-Labs

Início rápido

uvx mcp-fiscal-brasil

Para manter sempre atualizado: uvx cacheia a versão instalada. Use uvx mcp-fiscal-brasil@latest ou uvx --refresh mcp-fiscal-brasil para forçar a versão mais recente do PyPI.

Claude Desktop

Edite ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) ou %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "fiscal-brasil": {
      "command": "uvx",
      "args": ["mcp-fiscal-brasil"]
    }
  }
}

Reinicie o Claude Desktop. As ferramentas fiscais aparecem automaticamente, sem nenhuma chave de API.


Related MCP server: mcp-fiscal-brasil

Por que mcp-fiscal-brasil e não outros servidores MCP brasileiros?

Funcionalidade

mcp-fiscal-brasil

mcp-brasil

brasil-data-mcp

Foco

Vertical fiscal profunda

Dados públicos gerais

Dados públicos gerais

NF-e: parse, validação, DANFE, assinatura

Sim

Não

Não

SPED/eSocial: análise offline

Sim

Não

Não

Tabelas offline (NCM, CFOP, CNAE)

Sim

Não

Não

Reforma Tributária 2026 (IBS/CBS)

Sim

Não

Não

Simples Nacional/MEI

Sim

Não

Não

Certidão federal/FGTS

Sim (orientação)

Não

Não

Certificado A1 (mTLS SEFAZ)

Sim (opt-in)

Não

Não

Zero-cadastro, zero chave obrigatória

Sim

Parcial (3 APIs exigem chave)

Sim

Tools agênticas de alto nível

Sim (6 tools)

Parcial

Não

Linguagem de implementação

Python

Python

Node.js

mcp-brasil (1.6k stars) e brasil-data-mcp cobrem dados públicos gerais - CEP, bancos, feriados, economia. Este projeto faz algo diferente: é uma vertical fiscal, com parsing offline de XML, validação XSD, tabelas de referência embutidas e suporte à Reforma 2026. Focos diferentes, públicos distintos.


O que é

mcp-fiscal-brasil conecta assistentes de IA, ERPs, CRMs e automações internas ao universo fiscal brasileiro: CNPJ, CPF, Simples Nacional, NFe, NFSe, SPED, eSocial, certidões e due diligence de fornecedores.

Ele não tenta ser um catálogo genérico de dados públicos. A proposta é ser uma vertical de produto: transformar consultas fiscais fragmentadas em tools seguras, composáveis e prontas para agentes.

Workflows que vendem sozinho

Workflow

Tool principal

Resultado

Due diligence de fornecedor

risk_score_supplier

Score 0-100, risco, fatores e recomendação de contratação

Triagem em lote

consultar_empresas_lote

Vários CNPJs em uma chamada, com compliance + score por empresa

Compliance de CNPJ

analyze_cnpj_compliance

CNPJ + Simples/MEI + CNAE em relatório acionável

Validação de NFe

validate_nfe_full

XML + chave + emissor, com issues estruturadas

Sumário de SPED

summarize_sped

Resumo executivo, período, empresa, blocos e inconsistências

Planejamento tributário

compare_tax_regimes

Comparativo MEI, Simples, Lucro Presumido e Lucro Real


🌎 Demo ao vivo

Web UI demo hospedada (Render free tier, pode demorar 30s no primeiro acesso pra acordar):

Deploy to Render

Você pode clicar no botão acima pra hostear sua própria instância em 3 cliques no Render.com.

Veja docs/getting-started/deploy.md para outras opções (Fly.io, auto-host via Docker).


✨ Novidades v0.2.x

Versão de evolução com 4 frentes:

  • 8 novas fontes de dados: CNAE, CPF, Simples Nacional, MEI, IBGE, CEP, Empresa consolidada, Certidões

  • Tools agênticas (alto nível): analyze_cnpj_compliance, risk_score_supplier, consultar_empresas_lote, compare_tax_regimes, validate_nfe_full, summarize_sped

  • Múltiplas interfaces: além do servidor MCP, agora CLI (mcp-fiscal), REST API (mcp-fiscal-api) com Web UI demo, e wrapper Node.js em preview (npm-wrapper/)

  • Production-grade: HTTP client com retry exponencial, cache pluggável, rate-limit por host, logs JSON estruturados

# CLI standalone
mcp-fiscal cnpj 12345678000190
mcp-fiscal compliance 12345678000190
mcp-fiscal regimes --faturamento 500000 --setor serviços --folha 180000

# REST API + Web UI demo
mcp-fiscal-api  # http://localhost:8000

# Node.js
import { analyzeCompliance } from "mcp-fiscal-brasil";

Veja CHANGELOG.md para detalhes.


Por que este projeto existe?

O Brasil tem uma das infraestruturas fiscais mais complexas do mundo. São 27 SEFAZs estaduais, NFe + NFSe + SPED + eSocial, milhares de municípios com portais próprios e milhões de empresas tentando manter conformidade fiscal todos os dias.

Antes deste projeto, integrar IA com qualquer dado fiscal brasileiro exigia desenvolvimento customizado, autenticação em múltiplos portais, e conhecimento profundo de cada API governamental. Cada consulta era um projeto.

MCP Fiscal Brasil resolve isso em uma linha: instale o servidor, conecte ao seu assistente de IA, e comece a fazer perguntas em linguagem natural. O servidor cuida de tudo, consultando diretamente Receita Federal, BrasilAPI e SEFAZs estaduais.


🎬 Demonstração

Você:  "Consulte o CNPJ 00.000.000/0001-91 e liste os sócios"

IA:    Empresa: Banco do Brasil S.A.
       Fundada em: 12/10/1808
       Situação: ATIVA
       CNAE principal: 6422100 - Bancos múltiplos com carteira comercial

       Sócios (QSA):
       - União Federal - Sócio-Administrador (60,82%)
       - BNDESPar - Sócio (10,32%)
Você:  "A chave NFe 35240300623904000197550010000012341234567890 é válida?"

IA:    Chave válida!
       Estado de origem: SP (São Paulo)
       Data de emissão: março/2024
       CNPJ emitente: 00.623.904/0001-97
       Número da nota: 000001234
       Dígito verificador: correto (módulo 11)
Você:  "A empresa 12.345.678/0001-90 é do Simples Nacional?"

IA:    Sim! Empresa optante do Simples Nacional.
       Data de opção: 01/01/2020
       Modalidade: MEI - Microempreendedor Individual
Você:  "O SEFAZ de São Paulo está online agora?"

IA:    Status SEFAZ SP: OPERACIONAL
       Serviço de autorização de NFe funcionando normalmente.
       Última verificação: agora.

🛠 Ferramentas Disponíveis

Ferramentas de baixo nível para dados fiscais e ferramentas agênticas de alto nível para decisão operacional.

Tools agênticas

Ferramenta

Quando usar

analyze_cnpj_compliance

Relatório consolidado de compliance fiscal de um CNPJ

risk_score_supplier

Aprovar, investigar ou recusar fornecedor

consultar_empresas_lote

Triar carteira de fornecedores com score e erro por CNPJ

compare_tax_regimes

Comparar regimes tributários por cenário

validate_nfe_full

Validar uma NFe completa a partir do XML

summarize_sped

Transformar SPED em resumo executivo

✅ Ferramentas Funcionais (usáveis agora)

Funcionam 100% sem chaves de API. Instale e use imediatamente.

Módulo

Ferramenta

Descrição

API

CNPJ

consultar_cnpj

Dados completos: razão social, sócios, CNAE, endereço

BrasilAPI (grátis) + cpfcnpj.com.br (premium, opt-in)

CNPJ

consultar_simples_nacional

Optante Simples/MEI com datas de entrada e exclusão

BrasilAPI (grátis)

NFe

validar_chave_nfe

Valida dígito + extrai UF, CNPJ, data, número

Offline

NFe

consultar_nfe

Consulta NFe completa pela chave de 44 dígitos

BrasilAPI (grátis) + cpfcnpj.com.br (premium, opt-in)

NFe

consultar_nfce

NFC-e (modelo 65) pela chave de 44 dígitos; consulta completa exige token (pacote 102), senão tenta fontes públicas com dados parciais

cpfcnpj.com.br (pacote 102) + fontes públicas (parcial)

NFe

parse_nfe_xml

Parseia XML bruto de NF-e/NFC-e e retorna dados estruturados

Offline

NFe

gerar_danfe

Gera DANFE PDF (A4) a partir do XML de NF-e (mod 55)

Offline

NFe

validar_assinatura_nfe

Valida assinatura XMLDSig e extrai dados do certificado

Offline

NFe

consultar_status_sefaz

Status real do webservice SEFAZ por estado via NfeStatusServico4 (requer cert A1)

SEFAZ (mTLS)

NFe

baixar_nfe_distribuicao

Baixa documentos via NFeDistribuicaoDFe (requer cert A1 local)

SEFAZ (mTLS)

NFe

manifestar_nfe

Manifesta destinatario em NF-e via NFeRecepcaoEvento (requer cert A1)

SEFAZ (mTLS)

CPF

validar_cpf

Validação de dígito verificador

Offline

SPED

analisar_sped

Analisa arquivo EFD/ECD/ECF: período, empresa, erros

Offline

SPED

listar_registros_sped

Filtra registros por tipo (C100, E110, etc.)

Offline

eSocial

listar_eventos_esocial

Catálogo de eventos filtrável por grupo

Offline

eSocial

validar_evento_esocial

Validação básica de estrutura XML

Offline


🧭 Ferramentas de Orientação

Retornam URLs e instruções - exigem ação manual nos portais governamentais.

Módulo

Ferramenta

O que retorna

NFSe

consultar_nfse

URL do portal NFSe do município + sistema utilizado

Certidões

consultar_certidao_federal

URL do e-CAC para emissão de CND federal

Certidões

consultar_certidao_fgts

URL do portal Caixa para consulta do CRF


🔐 Ferramentas com Certificado A1 (opt-in)

As tools baixar_nfe_distribuicao, manifestar_nfe e consultar_status_sefaz requerem um certificado digital A1 (.pfx/.p12). mTLS é exigência de transporte de todo webservice SEFAZ, inclusive a consulta de status - não há como consultar o status real sem certificado.

  • O certificado e a senha nunca são enviados a nenhum servidor externo.

  • A autenticação mTLS e a assinatura XMLDSig são feitas localmente.

  • baixar_nfe_distribuicao e manifestar_nfe recebem o caminho do certificado como parâmetro da própria tool (.pfx/.p12 local).

  • consultar_status_sefaz (via servidor MCP/API REST) usa o certificado configurado nas variáveis de ambiente abaixo, e se conecta ao webservice próprio da UF consultada ou ao ambiente virtual (SVRS/SVAN) quando a UF não tem infraestrutura própria.

  • As demais tools (parse, DANFE, assinatura, consultas de CNPJ/NFe via BrasilAPI) funcionam sem certificado.

Configuração (variáveis em .env ou secret do provedor de deploy - ver .env.example):

Variável

Descrição

NFE_CERTIFICADO_PATH

Caminho absoluto do .pfx/.p12 montado no container

NFE_CERTIFICADO_SENHA

Senha do certificado (sempre via gestor de segredos, nunca em .env versionado)

NFE_EMITENTE_CNPJ

CNPJ do titular do certificado (14 dígitos, opcional)

NFE_AMBIENTE

producao ou homologacao (padrão producao)

Sem NFE_CERTIFICADO_PATH/NFE_CERTIFICADO_SENHA, consultar_status_sefaz levanta FiscalConfigurationError e o endpoint HTTP GET /v1/nfe/status-sefaz responde 503 - o chamador deve tratar isso como "sem certificado configurado", não como SEFAZ fora do ar (falha pontual de rede em uma UF especifica, essa sim, degrada omitindo a UF em vez de derrubar a chamada). GET /v1/fiscal/certificado/status informa apenas se há certificado configurado e válido (sem titular nem CNPJ - endpoint sem autenticação, não deve permitir reconhecimento de identidade), sem nunca expor o arquivo ou a senha.


☁️ Provedor premium opcional: cpfcnpj.com.br (opt-in)

O projeto continua gratuito, sem cadastro e sem chave de API por padrão. Para quem precisa de cobertura e atualidade de nível empresarial, a cpfcnpj.com.br pode ser habilitada como uma fonte premium opt-in, sem alterar em nada o comportamento gratuito padrão.

Enquanto o token não é configurado, tudo funciona como antes, usando apenas as fontes gratuitas (BrasilAPI, ReceitaWS e Portal NFe). Ao definir CPFCNPJ_TOKEN, o provedor passa a ser consultado primeiro, e as fontes gratuitas seguem como fallback automático, de forma transparente.

O que a fonte premium acrescenta a este projeto fiscal:

  • Dados oficiais em tempo real (D+0): cadastro atualizado direto na origem, sem depender de janelas de sincronização de bases intermediárias.

  • Sem bases vazadas ou raspadas: os dados vêm de fontes oficiais, com procedência conhecida, e não de dumps de terceiros.

  • Conformidade com certificações internacionais (ISO/IEC 27001 de segurança da informação, ISO/IEC 27701 de privacidade e ISO 37301 de gestão de conformidade), reforçando privacidade e tratamento adequado dos dados.

  • Cobre a consulta de NF-e por chave, que hoje depende de fontes públicas instáveis, e adiciona NFC-e (modelo 65), ainda não coberta pelas APIs gratuitas.

Ferramentas cobertas quando o token está ativo:

Ferramenta

Fonte premium

Pacote

Documentação

consultar_cnpj

cpfcnpj.com.br

5 ou 6

dev/

consultar_nfe

cpfcnpj.com.br

100 (modelo 55)

#op-get-token-100-chave

consultar_nfce

cpfcnpj.com.br

102 (modelo 65)

#op-get-token-102-chave

O consultar_nfce retorna a NFC-e completa apenas com o token configurado (pacote 102). Sem token, ele recorre às fontes públicas e pode devolver dados parciais da chave. A cobertura on-line do pacote 102 está disponível em São Paulo (SP) e Minas Gerais (MG); as demais UFs exigem habilitação sob demanda e podem retornar o erro 204 (sem consumo de crédito). Detalhes de cobertura em cpfcnpj.com.br/dev/.

Configuração (todas opcionais, ver .env.example):

Variável

Descrição

Padrão

CPFCNPJ_TOKEN

Token da conta em cpfcnpj.com.br. Vazio = fonte premium desligada.

(vazio)

CPFCNPJ_BASE_URL

URL base da API premium. Aceita somente https:// (o token trafega no caminho da URL)

https://api.cpfcnpj.com.br

CPFCNPJ_CNPJ_PACKET

Pacote de CNPJ: 5 (enxuto) ou 6 (completo)

6

Trate o token como segredo: use o gestor de segredos do seu provedor de deploy, nunca um .env versionado em produção.


🧪 Ferramentas Experimentais

Requerem APIs pagas ou têm cobertura limitada.

Módulo

Ferramenta

Limitação

CNPJ

listar_cnpjs_por_nome

Receita Federal não disponibiliza busca por nome em API pública


🚀 Instalação

A forma mais simples, sem instalar nada permanentemente:

uvx mcp-fiscal-brasil

O que é uvx? É o gerenciador de ferramentas do uv, que baixa e executa pacotes Python em ambiente isolado, sem poluir seu sistema. Se ainda não tem o uv: curl -LsSf https://astral.sh/uv/install.sh | sh

Mantendo atualizado via PyPI: use uvx mcp-fiscal-brasil@latest ou uvx --refresh mcp-fiscal-brasil para forçar a versão mais recente. O uvx cacheia localmente, então sem @latest você pode continuar numa versão antiga.


⚙️ Configuração por Cliente MCP

Cole o trecho abaixo no arquivo de configuração do seu cliente. Nenhuma chave de API é necessária.

Claude Desktop

Edite ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) ou %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "fiscal-brasil": {
      "command": "uvx",
      "args": ["mcp-fiscal-brasil"]
    }
  }
}

Reinicie o Claude Desktop. As ferramentas fiscais e agênticas aparecem automaticamente.

Claude Code (CLI)

claude mcp add fiscal-brasil -- uvx mcp-fiscal-brasil

Cursor / .mcp.json

Crie ou edite .cursor/mcp.json (ou .mcp.json na raiz do projeto):

{
  "mcpServers": {
    "fiscal-brasil": {
      "command": "uvx",
      "args": ["mcp-fiscal-brasil"]
    }
  }
}

VS Code + Continue

Adicione ao settings.json:

{
  "continue.mcpServers": {
    "fiscal-brasil": {
      "command": "uvx",
      "args": ["mcp-fiscal-brasil"]
    }
  }
}

Docker

docker run --rm -i \
  -e MCP_FISCAL_LOG_LEVEL=INFO \
  ghcr.io/dehor-labs/mcp-fiscal-brasil:latest

🛠 Instalação permanente (alternativa)

Prefere instalar uma vez e manter no PATH?

# via pip
pip install mcp-fiscal-brasil

# via uv (recomendado para projetos Python)
uv add mcp-fiscal-brasil

Após a instalação, os snippets JSON acima funcionam com "command": "mcp-fiscal-brasil" (sem o uvx).

A partir do código-fonte

git clone https://github.com/DeHor-Labs/mcp-fiscal-brasil.git
cd mcp-fiscal-brasil
pip install -e .

🔑 Variáveis de Ambiente

Todas as variáveis são opcionais. O servidor funciona sem nenhuma configuração.

Variável

Descrição

Padrão

MCP_FISCAL_LOG_LEVEL

Nível de log: DEBUG, INFO, WARNING

INFO

BRASILAPI_BASE_URL

URL base da BrasilAPI (para ambientes customizados)

https://brasilapi.com.br/api

HTTP_TIMEOUT

Timeout em segundos para chamadas HTTP

30

CPFCNPJ_TOKEN

Token do provedor premium opt-in cpfcnpj.com.br. Vazio = desligado (padrão gratuito intacto)

(vazio)

CPFCNPJ_BASE_URL

URL base da API premium cpfcnpj.com.br. Aceita somente https://

https://api.cpfcnpj.com.br

CPFCNPJ_CNPJ_PACKET

Pacote de CNPJ na cpfcnpj.com.br: 5 ou 6

6


Modos de Uso

O mcp-fiscal-brasil funciona de quatro formas:

Modo

Para quem

Como

MCP Server

Usuários de IA (Claude, Cursor, GPT)

Instala e configura no assistente

SDK Python

Desenvolvedores de apps fiscais/contábeis

Importa e usa no código

CLI

Operação, scripts e automações locais

Usa mcp-fiscal ...

REST API + Web UI

Integração HTTP e demo pública

Usa mcp-fiscal-api


🐍 Uso como Biblioteca Python (SDK)

Além de funcionar como servidor MCP, você pode importar e usar diretamente no seu código Python - sem servidor, sem configuração extra.

Início Rápido

import asyncio
from mcp_fiscal_brasil import FiscalBrasil

async def main():
    async with FiscalBrasil() as fiscal:
        empresa = await fiscal.consultar_cnpj("00.000.000/0001-91")
        print(empresa["razao_social"])  # Banco do Brasil S.A.
        print(empresa["situacao_cadastral"])  # ATIVA

asyncio.run(main())

Validações Offline (sem API, instantâneo)

from mcp_fiscal_brasil import FiscalBrasil

fiscal = FiscalBrasil()

# Validações locais - sem chamada de rede
print(fiscal.validate_cpf("529.982.247-25"))       # True
print(fiscal.validate_cnpj("11.222.333/0001-81"))  # True / False
print(fiscal.validate_chave_nfe("3524...44 digitos..."))  # dict com detalhes

Integração com FastAPI

from fastapi import FastAPI
from mcp_fiscal_brasil import FiscalBrasil

app = FastAPI()
fiscal = FiscalBrasil()

@app.get("/cnpj/{cnpj}")
async def consultar(cnpj: str):
    async with fiscal:
        return await fiscal.consultar_cnpj(cnpj)

Integração com Django

# views.py
import asyncio
from mcp_fiscal_brasil import FiscalBrasil
from django.http import JsonResponse

def consulta_cnpj(request, cnpj):
    async def buscar():
        async with FiscalBrasil() as fiscal:
            return await fiscal.consultar_cnpj(cnpj)
    dados = asyncio.run(buscar())
    return JsonResponse(dados)

Cadastro Automático de Fornecedor (exemplo ERP)

import asyncio
from mcp_fiscal_brasil import FiscalBrasil

async def cadastrar_fornecedor(cnpj: str, db_session):
    async with FiscalBrasil() as fiscal:
        if not fiscal.validate_cnpj(cnpj):
            raise ValueError("CNPJ inválido")

        dados = await fiscal.consultar_cnpj(cnpj)
        simples = await fiscal.consultar_simples_nacional(cnpj)

        await db_session.execute(
            "INSERT INTO fornecedores (cnpj, razao_social, simples) VALUES (?, ?, ?)",
            [cnpj, dados["razao_social"], simples["optante"]]
        )

Validação em Lote

import asyncio
from mcp_fiscal_brasil import FiscalBrasil

fiscal = FiscalBrasil()

documentos = ["529.982.247-25", "000.000.000-00", "11.222.333/0001-81"]

resultados = [
    {"doc": doc, "válido": fiscal.validate_cpf(doc) or fiscal.validate_cnpj(doc)}
    for doc in documentos
]
# [{'doc': '529.982.247-25', 'válido': True}, ...]

🏗 Arquitetura

Claude / GPT / Cursor / qualquer cliente MCP
           |
           | Model Context Protocol (stdio)
           v
    mcp-fiscal-brasil
           |
    +------+-------+--------+--------+--------+-------+--------+
    |      |       |        |        |        |       |        |
   CNPJ   CPF    NFe      NFSe   Simples    SPED  eSocial Certidões
    |      |       |        |        |        |       |        |
    v      v       v        v        v        v       v        v
BrasilAPI  --   SEFAZ   Portais   Receita  Parser  Catálogo  URLs
ReceitaWS       estaduais municipais Federal  local   local  governamentais

Fontes de dados:

  • BrasilAPI - CNPJ, CEP, bancos (open source, sem autenticação)

  • ReceitaWS - CNPJ (fallback)

  • SEFAZs estaduais - Status de serviço e consulta de NFe

  • Receita Federal - Simples Nacional e certidões (orientação de acesso)


📍 Roadmap

  • v0.1.x - Consultas CNPJ, CPF, NFe, Simples Nacional e SPED; ~14 tools MCP

  • v0.2.x - Infra production-grade (_core), CLI, REST API, Web UI demo, wrapper npm/Node.js e tools agênticas (compliance, due diligence, comparativo de regimes); ~20 tools MCP

  • v0.3.x - Tabelas fiscais offline (NCM/TIPI, CFOP, CST, CEST, ICMS interestadual) e indexadores BCB (Selic, IPCA, PTAX, correção monetária); ~36 tools MCP

  • v0.4.x - Módulo NF-e completo (parse, DANFE, assinatura XMLDSig, distribuição mTLS, manifestação do destinatário) e simulador da Reforma Tributária IBS/CBS (LC 214/2025); ~42 tools MCP

  • v0.5.x - Módulo de importação (II, IPI, PIS/COFINS-importação, ICMS grossed-up, AFRMM, Siscomex) por NCM; circuit breaker NFS-e; correções SPED e path injection; automação de release; 45 tools MCP

  • v0.6.x - NFC-e modelo 65 (DANFE cupom, autorizacao e cancelamento); NFS-e por provedor/municipio; validação XSD completa NF-e e SPED

  • v0.7.x - eSocial versionado (S-1.1); cache persistente entre sessões; LGPD audit trail

  • v1.0.0 - Suíte fiscal com contratos de API estáveis, cobertura operacional ampliada e SLA de manutenção documentado


Como acompanhar

GitHub Discussions GitHub Stars

  • Releases: clique em Watch -> Releases no topo do repositório para ser notificado a cada versão nova

  • Discussions: github.com/DeHor-Labs/mcp-fiscal-brasil/discussions - canal para sugestões de feature, dúvidas fiscais e técnicas, e casos de uso. Sugestões feitas aqui entram no roadmap de verdade

  • Newsletter: acompanhe os releases comentados na LinkedIn Newsletter MCP Fiscal Brasil - cada edição explica o que chegou, o que foi corrigido e o que vem por ai. Assinar agora

  • Issues: bugs com contexto completo (versão, XML de exemplo sem dados reais, comportamento esperado vs. obtido)


🤝 Contribuindo

Contribuições são bem-vindas!

# 1. Clone o repo ou seu fork
git clone https://github.com/DeHor-Labs/mcp-fiscal-brasil.git
cd mcp-fiscal-brasil

# 2. Instale dependências de desenvolvimento
pip install -e ".[dev]"
pre-commit install

# 3. Crie sua branch
git checkout -b feature/meu-recurso

# 4. Implemente, teste e verifique
python scripts/check_release_metadata.py
ruff check src/ tests/
ruff format --check src/ tests/
mypy src/
pytest

# 5. Abra um Pull Request

Veja as issues abertas - especialmente as marcadas com good first issue.

Cada módulo segue o padrão client.py + schemas.py + tools.py, o que torna simples adicionar novos módulos fiscais.


📄 Licença

MIT - veja LICENSE para detalhes.


Available Tools

44 tools
analisar_spedA

Analisa um arquivo SPED (EFD-ICMS/IPI, EFD-Contribuições, ECD ou ECF) e extrai informações sobre período, empresa, tipos de registros e possíveis erros. Recebe o conteúdo do arquivo como texto (formato pipe-delimitado).

Inputs: conteudo (required), nome_arquivo. Returns: object

analyze_cnpj_complianceA

Analise consolidada de compliance fiscal de um CNPJ. Combina dados cadastrais (Receita), regime tributário (Simples Nacional), status MEI e CNAE em um relatório unico com score 0-100, risco classificado (baixo/medio/alto/critico) e achados acionaveis. Use para decisão de contratar/recusar/investigar uma empresa em uma chamada.

Inputs: cnpj (required). Returns: object

baixar_nfe_distribuicaoA

Baixa documentos fiscais via NFeDistribuicaoDFe (SEFAZ) usando certificado A1 local. REQUER certificado digital A1 (.pfx/.p12) do proprio usuario instalado localmente. O certificado NUNCA e enviado a nenhum servidor - a autenticacao e feita localmente via mTLS. Suporta busca incremental (distNSU), por NSU especifico (consNSU) ou por chave (consChNFe). A Ciencia da Operacao (210200) e prerequisito para obter o XML completo (procNFe).

Inputs: caminho_certificado (required), senha (required), cnpj_cpf (required), uf (required), +6 more. Returns: object

buscar_cnaeA

Busca atividades econômicas CNAE por texto na descrição. Retorna lista de subclasses que correspondem ao termo pesquisado. Útil para encontrar o código CNAE a partir do ramo de atividade desejado.

Inputs: texto (required). Returns: result

calcular_correcao_monetariaA

Calcula a correção monetária de um valor entre duas datas usando IPCA ou Selic. Busca as séries históricas do Banco Central do Brasil e aplica o fator acumulado ao valor informado. Útil para atualização de dívidas, contratos e obrigações fiscais.

Inputs: valor (required), data_inicio (required), data_fim (required), indice. Returns: object

calcular_tributos_importacaoA

Calcula os tributos de importação em cascata para um produto classificado por NCM. Purpose: estimar a carga tributária de importação (II, IPI, PIS/COFINS-importação, ICMS grossed-up, AFRMM e taxa Siscomex) para planejamento de custo de desembaraço. Quando usar: ao planejar uma importação e precisar estimar o custo total de tributos. IMPORTANTE: A alíquota II (aliquota_ii) deve ser informada pelo usuário conforme a TEC vigente em www.mdic.gov.br. Não há fonte offline estruturada para a TEC. Cascata: VA -> II -> IPI (base=VA+II) -> PIS/COFINS-imp (base=VA) -> ICMS por dentro (base=VA+II+IPI+PIS+COFINS) -> AFRMM/Siscomex. DISCLAIMER: Estimativa para planejamento. Não substitui SISCOMEX nem despachante. Antidumping, regimes especiais, acordos bilaterais e alíquotas diferenciadas de PIS/COFINS estão fora do escopo do MVP. Parâmetros: ncm (8 dígitos), valor_aduaneiro (R$), uf_importador (sigla UF), aliquota_ii (% TEC), modal (maritimo/aereo/terrestre/postal), frete_maritimo (R$, apenas modal marítimo), aliquota_pis (default 2,1%), aliquota_cofins (default 9,65%), aliquota_ipi_override (sobrescreve banco NCM).

Inputs: ncm (required), valor_aduaneiro (required), uf_importador (required), aliquota_ii (required), +5 more. Returns: object

compare_tax_regimesA

Compara regimes tributarios brasileiros (MEI, Simples Nacional, Lucro Presumido, Lucro Real) para um cenário de faturamento e setor. Retorna estimativa de alíquota efetiva, imposto anual e melhor opção. Util para planejamento tributário rápido. Setor: comércio, serviços ou indústria. Folha opcional impacta Fator R no Simples.

Inputs: faturamento_anual (required), setor (required), folha_pagamento_anual. Returns: object

consultar_aliquota_icmsA

Consulta as alíquotas do ICMS para operações interestaduais entre contribuintes. Purpose: calcular o DIFAL (Diferencial de Alíquota) e a alíquota interestadual aplicável na emissão de NF-e, conforme EC 87/2015 e Res. Senado Federal nº 22/1989. Quando usar: ao emitir NF-e interestadual, calcular DIFAL ou verificar a carga tributária de operações entre estados. Comportamento offline: calcula a partir de tabelas em memória; não requer conexão. NOTA: não cobre a alíquota de 4% para bens importados (Resolução SF 13/2012). Parâmetros: siglas de UF em maiúsculo (ex: 'SP', 'MG', 'RJ').

Inputs: uf_origem (required), uf_destino (required). Returns: object

consultar_aliquotas_importacaoA

Consulta alíquotas de referência para cálculo de tributos de importação por NCM. Purpose: obter a alíquota IPI do banco NCM/TIPI e os defaults de PIS/COFINS-importação antes de usar calcular_tributos_importacao. Quando usar: antes de calcular tributos de importação, para verificar a alíquota IPI do produto e conhecer os defaults de PIS/COFINS aplicáveis. IMPORTANTE: A alíquota II (Imposto de Importação / TEC) NÃO está disponível offline. Consulte www.mdic.gov.br e informe manualmente em calcular_tributos_importacao. Comportamento offline: lê do banco SQLite bundled (TIPI); não requer conexão. Parâmetro: código NCM com 8 dígitos, com ou sem pontuação (ex: '22030000' ou '2203.00.00').

Inputs: ncm (required). Returns: object

consultar_cepA

Consulta o endereço completo a partir de um CEP brasileiro. Retorna logradouro, bairro, cidade, estado e serviço de origem. Aceita CEP com ou sem hífen (ex: '01001-000' ou '01001000').

Inputs: cep (required). Returns: object

consultar_certidao_federalA

Orienta sobre como consultar a Certidão Negativa de Débitos (CND) da Receita Federal e PGFN para CNPJ ou CPF. Fornece URLs de emissão e verificação e alternativas para automação.

Inputs: cnpj_cpf (required). Returns: object

consultar_certidao_fgtsB

Orienta sobre como consultar a Certidão de Regularidade do FGTS (CRF) para um CNPJ. Fornece URL do portal da Caixa e alternativas para automação.

Inputs: cnpj (required). Returns: object

consultar_cestA

Consulta o Código Especificador da Substituição Tributária (CEST). Purpose: identificar produtos sujeitos à substituição tributária do ICMS, conforme Convênio ICMS 92/2015 e suas atualizações. Quando usar: ao emitir NF-e com produtos sujeitos ao ICMS-ST. Comportamento offline: lê do banco SQLite bundled. AVISO: o banco pode conter apenas uma amostra; execute scripts/build_tabelas_db.py para popular a tabela completa. Formato do parâmetro: 7 dígitos numéricos, com ou sem pontuação (ex: '0100700' ou '01.007.00').

Inputs: cest (required). Returns: object

consultar_cfopA

Consulta o Código Fiscal de Operações e Prestações (CFOP). Purpose: identificar a natureza jurídica de uma operação fiscal para preenchimento de NF-e, SPED EFD-ICMS/IPI e escrituração contábil. Quando usar: ao emitir nota fiscal, classificar entradas/saídas ou analisar obrigações acessórias. Comportamento offline: lê dicionário em memória com todos os grupos CFOP; não requer conexão. Formato do parâmetro: 4 dígitos numéricos (ex: '5102', '6101', '1556'). Grupos: 1/2/3 = entradas (estadual/interestadual/exterior); 5/6/7 = saídas (estadual/interestadual/exterior).

Inputs: cfop (required). Returns: object

consultar_cnaeA

Consulta uma atividade econômica CNAE pelo código de subclasse (7 dígitos). Retorna código e descrição oficial da atividade conforme tabela IBGE. Útil para identificar o ramo de atuação de empresas a partir do código CNAE.

Inputs: codigo (required). Returns: object

consultar_cnpjB

Consulta os dados cadastrais completos de uma empresa pelo CNPJ. Retorna razão social, endereço, atividades econômicas (CNAE), sócios (QSA), situação cadastral e porte da empresa. Aceita CNPJ com ou sem formatação (pontos, barra, traço).

Inputs: cnpj (required). Returns: object

consultar_empresa_completaA

Consulta dados enriquecidos de uma empresa brasileira combinando informações da Receita Federal (CNPJ) e do Simples Nacional em uma única chamada. Retorna razão social, situação cadastral, porte, regime tributário (MEI/Simples), CNAE principal e secundárias, endereço e natureza jurídica.

Inputs: cnpj (required). Returns: object

consultar_empresas_loteA

Consulta em lote múltiplos CNPJs e devolve, em uma única chamada, o resumo de compliance + score de risco de fornecedor para cada empresa. Útil para triagem rápida de carteira de fornecedores, com erros por CNPJ retornados se algum dado falhar.

Inputs: cnpjs (required), criterios_estritos. Returns: object

consultar_estado_ibgeA

Consulta os dados de um estado brasileiro pela sigla da UF via API IBGE. Retorna id, sigla, nome oficial e região geográfica do estado.

Inputs: uf (required). Returns: object

consultar_municipios_ibgeA

Consulta municípios brasileiros via API IBGE Localidades. Opcionalmente filtra por UF (sigla do estado). Retorna id, nome, microrregião e estado de cada município.

Inputs: uf. Returns: result

consultar_ncmA

Consulta a Nomenclatura Comum do Mercosul (NCM) de um produto. Purpose: identificar a classificação fiscal de mercadorias para emissão de NF-e, cálculo de IPI e preenchimento do SPED. Quando usar: ao emitir nota fiscal, fazer importação/exportação ou calcular tributos. Comportamento offline: lê do banco SQLite bundled; não requer conexão. AVISO: o banco pode conter apenas uma amostra da TIPI completa (~10.515 registros); execute scripts/build_tabelas_db.py para popular a tabela completa. Formato do parâmetro: 8 dígitos numéricos, com ou sem pontuação (ex: '84713019' ou '8471.30.19').

Inputs: ncm (required). Returns: object

consultar_nfeA

Consulta os dados de uma Nota Fiscal Eletrônica (NFe) pela chave de acesso de 44 dígitos. A chave pode ser encontrada no DANFE (documento impresso da nota). Retorna emitente, destinatário, itens, valores e protocolo de autorização.

Inputs: chave_acesso (required). Returns: object

consultar_nfseA

Consulta dados de uma NFSe (Nota Fiscal de Serviço Eletrônica). ATENÇÃO: NFSe não possui padrão nacional - cada município tem seu próprio sistema. Esta ferramenta orienta sobre como acessar o portal correto do município.

Inputs: numero (required), municipio (required), uf (required), cnpj_prestador. Returns: object

consultar_simples_nacionalA

Consulta se uma empresa é optante do Simples Nacional ou MEI. Retorna situação atual, datas de opção e exclusão do regime simplificado.

Inputs: cnpj (required). Returns: object

consultar_status_meiA

Consulta o status de MEI (Microempreendedor Individual) e Simples Nacional de um CNPJ via BrasilAPI. Retorna se a empresa é optante pelo MEI e/ou Simples Nacional, com as respectivas datas de opção e exclusão quando disponíveis.

Inputs: cnpj (required). Returns: object

consultar_status_sefazA

Consulta o status atual do serviço SEFAZ de um estado brasileiro. Verifica se o webservice da SEFAZ para emissão de NFe está operacional. Útil para diagnosticar falhas de transmissão de notas fiscais.

Inputs: uf (required). Returns: object

gerar_danfeA

Gera o DANFE (Documento Auxiliar da Nota Fiscal Eletronica) em PDF a partir do XML de NF-e. Suporta apenas NF-e modelo 55. O PDF e retornado em base64. ATENCAO: o XML deve conter o namespace do portal fiscal (xmlns='http://www.portalfiscal.inf.br/nfe'). Nao e necessario certificado digital - funciona apenas com o XML.

Inputs: xml_content (required). Returns: object

ipca_periodoA

Consulta o IPCA (Índice de Preços ao Consumidor Amplo) acumulado mensal do Banco Central do Brasil (BCB/SGS série 433) para um período. Retorna variação percentual mensal. Útil para cálculos de inflação e correção monetária.

Inputs: data_inicio (required), data_fim. Returns: result

listar_cnpjs_por_nomeA

Busca empresas pelo nome empresarial ou razão social. Quando usar: quando só se conhece o nome da empresa e não o CNPJ; não usar quando o CNPJ já é conhecido (prefira consultar_cnpj). Comportamento: APIs públicas gratuitas não cobrem busca textual por nome; a ferramenta retorna orientação para obter o CNPJ via fontes adequadas. Parâmetros: nome (obrigatório), uf (sigla do estado, opcional).

Inputs: nome (required), uf. Returns: result

listar_eventos_esocialA

Lista os eventos do eSocial com nome, grupo e descrição. Pode filtrar por grupo: 'Tabelas', 'Não Periodicos', 'Periodicos' ou 'Exclusao'.

Inputs: grupo. Returns: result

listar_registros_spedA

Lista todas as ocorrências de um tipo de registro específico em um arquivo SPED. Exemplo: buscar todos os registros C100 (documentos fiscais) ou E110 (apuração ICMS).

Inputs: conteudo (required), tipo_registro (required). Returns: result

manifestar_nfeA

Manifesta o destinatario em uma NF-e via NFeRecepcaoEvento. REQUER certificado digital A1 (.pfx/.p12) do proprio usuario instalado localmente. O certificado NUNCA e enviado a nenhum servidor - a assinatura e feita localmente. Eventos: 210200 (Ciencia), 210210 (Confirmacao), 210220 (Desconhecimento), 210240 (Operacao nao Realizada, requer justificativa). A Ciencia (210200) e prerequisito obrigatorio para obter o XML completo da NF-e.

Inputs: chave (required), tipo_evento (required), caminho_certificado (required), senha (required), +6 more. Returns: object

parse_nfe_xmlA

Parseia o XML completo de uma NF-e ou NFC-e e retorna os dados estruturados. Aceita XML com ou sem o involucro e com ou sem namespace do portal fiscal. Util para extrair emitente, destinatario, itens, totais e protocolo a partir do XML bruto.

Inputs: xml_content (required). Returns: object

ptax_dataA

Consulta a cotação PTAX oficial do Banco Central do Brasil (compra e venda) para uma data e moeda específicas. A PTAX é a taxa de câmbio de referência usada em contratos e operações cambiais. Só disponível para dias úteis.

Inputs: data (required), moeda. Returns: object

risk_score_supplierA

Calcula score de risco (0-100) para due diligence de fornecedor. Combina ComplianceReport com ajustes conservadores para contratacao. Retorna recomendacao binaria (aprovar/aprovar_com_ressalvas/investigar/recusar). Opcao criterios_estritos=true reduz score em 10 para politicas anti-corrupcao.

Inputs: cnpj (required), criterios_estritos. Returns: object

simular_transicao_reforma_tributariaA

Simula o impacto da Reforma Tributaria (LC 214/2025) ano a ano de 2026 a 2033. Compara a carga do regime antigo (PIS/COFINS + ICMS ou ISS) com a do regime novo (CBS + IBS), mostrando o blend da transicao conforme o cronograma legal. Setores: comercio, servicos ou industria. Regimes: Simples Nacional, Lucro Presumido ou Lucro Real. Informe aliquota_icms_atual ou aliquota_iss_atual para maior precisao. Retorna projecao anual com premissas e disclaimers obrigatorios.

Inputs: faturamento_anual (required), setor (required), regime_atual (required), aliquota_icms_atual, +2 more. Returns: object

summarize_spedA

Sumarizacao executiva de um arquivo SPED (Fiscal, Contribuicoes, ECF ou ECD). Identifica tipo, extrai período, empresa, total de registros, blocos e produz resumo em pt-BR. Recebe caminho de arquivo .txt local.

Inputs: file_path (required). Returns: object

taxa_selicA

Consulta a taxa Selic efetiva diária do Banco Central do Brasil (BCB/SGS série 11) para um período. Retorna lista de pontos diários com data e taxa em % ao dia. Útil para cálculos de juros, correção monetária e análise de política monetária.

Inputs: data_inicio (required), data_fim. Returns: result

validar_assinatura_nfeA

Valida a assinatura digital XMLDSig de uma NF-e. Verifica a integridade do DigestValue e a assinatura criptografica do certificado. Extrai dados do certificado assinante: titular, CNPJ/CPF, validade e autoridade certificadora. Opcional: informe um CA bundle PEM para validar a cadeia de confianca ICP-Brasil.

Inputs: xml_content (required), ca_bundle. Returns: object

validar_chave_nfeA

Valida o formato e o dígito verificador de uma chave de acesso de NFe. Não consulta APIs - apenas verifica o cálculo matemático (módulo 11). Também extrai informações da chave: UF, data de emissão, CNPJ emitente e número da nota.

Inputs: chave_acesso (required). Returns: object

validar_cpfA

Valida o dígito verificador de um CPF brasileiro. Verificação matemática offline - não consulta APIs externas. A Receita Federal não disponibiliza API pública para dados de CPF.

Inputs: cpf (required). Returns: object

validar_cstA

Valida um Código de Situação Tributária (CST) ou Código de Situação da Operação no Simples Nacional (CSOSN). Purpose: confirmar se o código informado é válido para o regime tributário antes de emitir NF-e ou escriturar no SPED. Quando usar: ao preencher o campo CST/CSOSN na NF-e ou no SPED EFD. Comportamento offline: valida contra tabelas em memória (ICMS, PIS/COFINS, IPI, CSOSN); não requer conexão. Parâmetro 'regime': use 'normal' para Lucro Real/Presumido/Arbitrado ou 'simples' para Simples Nacional. Parâmetro 'cst': 3 dígitos para CST ICMS (ex: '000', '040'), 2 dígitos para CST PIS/COFINS/IPI (ex: '01', '50'), 3 dígitos para CSOSN (ex: '101', '400').

Inputs: cst (required), regime (required). Returns: object

validar_evento_esocialA

Realiza validação básica de estrutura de um XML de evento eSocial. Verifica presença do elemento raiz correto, código do evento e versão do leiaute.

Inputs: xml_conteudo (required). Returns: object

validate_nfe_fullA

Validacao consolidada de uma NFe a partir do XML: parse estrutural, validação do digito verificador da chave, verificacao de situacao do CNPJ emissor. Recebe caminho de arquivo XML local. Retorna relatório com chave, validade, issues e resumo.

Inputs: xml_path (required). Returns: object

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3.3/5.0

    Scored across 44 tools

    Disambiguation2/5

    Several tools have heavily overlapping purposes: consultar_simples_nacional and consultar_status_mei both return essentially the same Simples/MEI status, while analisar_sped and summarize_sped both extract period/company summaries from SPED. consultar_cnpj and consultar_empresa_completa also overlap on company data. Additionally, tools like listar_cnpjs_por_nome and consultar_nfse promise data lookup by their names but only return guidance, making selection confusing.

    Naming Consistency3/5

    Most tools follow a readable snake_case verb+noun pattern using Portuguese verbs like consultar_, validar_, and listar_. However, there is a notable Portuguese/English mix: analyze_cnpj_compliance, validate_nfe_full, summarize_sped, and compare_tax_regimes sit alongside mostly Portuguese names. Some tools also have no verb at all, such as taxa_selic, ipca_periodo, and ptax_data, so the naming pattern is not fully predictable.

    Tool Count2/5

    With 44 tools, this is well above the 25+ threshold and feels like multiple separate toolkits bundled into one server. The breadth of the Brazilian fiscal domain justifies some volume, but many tools could be consolidated, such as the duplicate Simples/MEI status lookups and the several overlapping SPED analysis tools.

    Completeness3/5

    The toolset covers a wide range of fiscal needs: CNPJ/CNAE lookup, NF-e validation and handling, SPED/eSocial support, tax code tables, import tax calculation, and monetary corrections. However, there are notable dead ends: listar_cnpjs_por_nome does not actually list CNPJs, consultar_nfse does not actually consult NFSe, and the certidão tools only provide URLs rather than data.

    Maintenance

    ActivityNo data
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      C
      maintenance
      Brazilian company-registry lookup via Receita Federal, allowing AI agents to query CNPJ data.
      100 npm
      MIT
    • A
      license
      B
      quality
      C
      maintenance
      Enables AI assistants and automation tools to query and analyze Brazilian fiscal data, including CNPJ, Simples Nacional, NF-e, NFS-e, SPED, eSocial, tax regime comparison, and supplier risk assessment without requiring API keys.
      44
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables AI assistants and business systems to query and validate Brazilian fiscal data and documents, including CNPJ/CPF, Simples Nacional/MEI, NF-e/NFS-e, SPED, eSocial, and supplier compliance, without mandatory API keys. It also supports offline reference tables, tax-regime comparison, due-diligence scoring, and 2026 IBS/CBS reform analysis through composable tools.
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      Enables AI agents to query Brazilian public data such as CEP, CNPJ, banks, holidays, business days, FIPE vehicle prices, DDD, IBGE municipalities, .br domains, and ISBN, with read-only tools and offline document validation.
      14
      305 npm
      MIT