Mcp Fiscal Brasil

O único servidor MCP com suporte nativo a NF-e, NFS-e, SPED, eSocial, Simples Nacional e Reforma Tributária 2026 (IBS/CBS) - sem conta, sem chave e sem configuração.

📚 Documentação · Instalação · Ferramentas · Workflows · Roadmap · Contribuindo

---

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.

---

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 | Nao | Nao | | SPED/eSocial: análise offline | Sim | Nao | Nao | | Tabelas offline (NCM, CFOP, CNAE) | Sim | Nao | Nao | | Reforma Tributária 2026 (IBS/CBS) | Sim | Nao | Nao | | Simples Nacional/MEI | Sim | Nao | Nao | | Certidão federal/FGTS | Sim (orientação) | Nao | Nao | | Certificado A1 (mTLS SEFAZ) | Sim (opt-in) | Nao | Nao | | Zero-cadastro, zero chave obrigatória | Sim | Parcial (3 APIs exigem chave) | Sim | | Tools agênticas de alto nível | Sim (6 tools) | Parcial | Nao | | 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):

[](https://render.com/deploy?repo=https://github.com/DeHor-Labs/mcp-fiscal-brasil)

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](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](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) | | 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_status_sefaz | Status do webservice SEFAZ por estado | BrasilAPI (grátis) | | NFe | consultar_nfe | Consulta NFe completa pela chave de 44 dígitos | BrasilAPI (grátis) | | 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 | 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 e manifestar_nfe requerem um certificado digital A1 (.pfx/.p12) instalado localmente no seu computador.

• O certificado e a senha nunca sao enviados a nenhum servidor externo.
• A autenticacao mTLS e a assinatura XMLDSig sao feitas localmente.
• Estas tools se conectam diretamente aos webservices da SEFAZ (Ambiente Nacional).
• Todas as demais tools (parse, DANFE, assinatura, consultas) funcionam sem certificado.

---

🧪 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 |

---

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
           |
    +------+-------+--------+--------+------

…

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [DeHor-Labs](https://github.com/DeHor-Labs)
- **Source:** [DeHor-Labs/mcp-fiscal-brasil](https://github.com/DeHor-Labs/mcp-fiscal-brasil)
- **License:** MIT
- **Homepage:** https://dehor-labs.github.io/mcp-fiscal-brasil/

Install and usage instructions live in the source repository linked above.