convez.ai
MCP ServerFinanceiroIntermediário
DeHor-Labs

MCP Fiscal Brasil

DeHor-Labs/mcp-fiscal-brasil

Compliance fiscal brasileiro via MCP para agentes de IA e automações

Ver no GitHub
BomPluginScore · de 0 a 100

Servidor MCP que conecta agentes de IA ao ecossistema fiscal brasileiro, oferecendo tools para validação de CNPJ/CPF, consulta de NFe/NFSe, análise SPED, eSocial e automação de compliance tributário. Simplifica workflows de due diligence, triagem em lote e planejamento tributário com dados públicos e certificados integrados.

Instalação

$npx convez-ai DeHor-Labs/mcp-fiscal-brasil

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
433
Forks
94
Acompanhando
14
Saúde
75%
Último commit
há 5 dias
Versão
v0.5.1
Issues abertas
32
Contribuidores
2

Casos de uso

  • Due diligence e risk scoring de fornecedores
  • Validação e triagem em lote de CNPJs
  • Análise de conformidade tributária e SPED
  • Automação de processos fiscais em ERPs e CRMs

Veredito

Ferramenta madura e bem estruturada para automação fiscal em Python. Cobre adequadamente o ecossistema tributário brasileiro (NFe, eSocial, SPED) com APIs seguras e composáveis, ideal para quem precisa integrar compliance fiscal em agentes Claude ou fluxos internos.

README

A tradução para o português deste README ainda está na fila.

mcp-name: io.github.dehor-labs/mcp-fiscal-brasil


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

WorkflowTool principalResultado
Due diligence de fornecedorrisk_score_supplierScore 0-100, risco, fatores e recomendação de contratação
Triagem em loteconsultar_empresas_loteVários CNPJs em uma chamada, com compliance + score por empresa
Compliance de CNPJanalyze_cnpj_complianceCNPJ + Simples/MEI + CNAE em relatório acionável
Validação de NFevalidate_nfe_fullXML + chave + emissor, com issues estruturadas
Sumário de SPEDsummarize_spedResumo executivo, período, empresa, blocos e inconsistências
Planejamento tributáriocompare_tax_regimesComparativo 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

FerramentaQuando usar
analyze_cnpj_complianceRelatório consolidado de compliance fiscal de um CNPJ
risk_score_supplierAprovar, investigar ou recusar fornecedor
consultar_empresas_loteTriar carteira de fornecedores com score e erro por CNPJ
compare_tax_regimesComparar regimes tributários por cenário
validate_nfe_fullValidar uma NFe completa a partir do XML
summarize_spedTransformar SPED em resumo executivo

✅ Ferramentas Funcionais (usáveis agora)

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

MóduloFerramentaDescriçãoAPI
CNPJconsultar_cnpjDados completos: razão social, sócios, CNAE, endereçoBrasilAPI (grátis)
CNPJconsultar_simples_nacionalOptante Simples/MEI com datas de entrada e exclusãoBrasilAPI (grátis)
NFevalidar_chave_nfeValida dígito + extrai UF, CNPJ, data, númeroOffline
NFeconsultar_status_sefazStatus do webservice SEFAZ por estadoBrasilAPI (grátis)
NFeconsultar_nfeConsulta NFe completa pela chave de 44 dígitosBrasilAPI (grátis)
CPFvalidar_cpfValidação de dígito verificadorOffline
SPEDanalisar_spedAnalisa arquivo EFD/ECD/ECF: período, empresa, errosOffline
SPEDlistar_registros_spedFiltra registros por tipo (C100, E110, etc.)Offline
eSociallistar_eventos_esocialCatálogo de eventos filtrável por grupoOffline
eSocialvalidar_evento_esocialValidação básica de estrutura XMLOffline

🧭 Ferramentas de Orientação

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

MóduloFerramentaO que retorna
NFSeconsultar_nfseURL do portal NFSe do município + sistema utilizado
Certidõesconsultar_certidao_federalURL do e-CAC para emissão de CND federal
Certidõesconsultar_certidao_fgtsURL do portal Caixa para consulta do CRF

🧪 Ferramentas Experimentais

Requerem APIs pagas ou têm cobertura limitada.

MóduloFerramentaLimitação
CNPJlistar_cnpjs_por_nomeReceita Federal não disponibiliza busca por nome em API pública

🚀 Instalação

Três linhas para começar:

pip install mcp-fiscal-brasil
claude mcp add fiscal-brasil -- mcp-fiscal-brasil
# Pronto! Pergunte ao Claude sobre qualquer empresa brasileira.
# Ou use como biblioteca Python:
from mcp_fiscal_brasil import FiscalBrasil

Via uv (recomendado)

uv add mcp-fiscal-brasil

A partir do código-fonte

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

⚙️ Configuração Detalhada

Claude Desktop

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

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

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

Claude Code (CLI)

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

Cursor

Adicione ao .cursor/mcp.json do projeto:

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

VS Code + Continue

Adicione ao settings.json:

{
  "continue.mcpServers": {
    "fiscal-brasil": {
      "command": "mcp-fiscal-brasil"
    }
  }
}

Docker

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

🔑 Variáveis de Ambiente

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

VariávelDescriçãoPadrão
MCP_FISCAL_LOG_LEVELNível de log: DEBUG, INFO, WARNINGINFO
BRASILAPI_BASE_URLURL base da BrasilAPI (para ambientes customizados)https://brasilapi.com.br/api
HTTP_TIMEOUTTimeout em segundos para chamadas HTTP30

Modos de Uso

O mcp-fiscal-brasil funciona de quatro formas:

ModoPara quemComo
MCP ServerUsuários de IA (Claude, Cursor, GPT)Instala e configura no assistente
SDK PythonDesenvolvedores de apps fiscais/contábeisImporta e usa no código
CLIOperação, scripts e automações locaisUsa mcp-fiscal ...
REST API + Web UIIntegração HTTP e demo públicaUsa 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, SPED
  • v0.2.x - CLI, REST API, Web UI demo, wrapper Node.js em preview e tools agênticas
  • v0.3.x - Lote de empresas, cache persistente, mais fontes públicas e relatórios exportáveis
  • v0.4.x - NFSe por provedor/município, validação XSD NFe/SPED e eSocial versionado
  • v1.0.0 - Suite fiscal com LGPD audit, contratos de API estáveis e cobertura operacional ampliada

🤝 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
pytest
ruff check src/
mypy src/

# 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.


Ver o original no GitHub

Bom para

Relacionados