mcp-fiscal-brasil

mcp-name: io.github.DeHor-Labs/mcp-fiscal-brasil

<p align="center">
  <img src="assets/banner.svg" width="800" alt="MCP Fiscal Brasil">
</p>

<p align="center">
  <strong>36 ferramentas fiscais. Zero API key. Zero cadastro. 100% open source.</strong><br>
  O primeiro MCP com suporte a Reforma Tributaria 2026 (IBS/CBS) - a camada open source para agentes de IA trabalharem com compliance fiscal brasileiro.
</p>

<p align="center">
  <a href="https://pypi.org/project/mcp-fiscal-brasil/"><img src="https://img.shields.io/pypi/v/mcp-fiscal-brasil?color=009c3b&label=PyPI" alt="PyPI version"></a>
  <a href="https://www.python.org/downloads/"><img src="https://img.shields.io/badge/python-3.10%2B-002776?logo=python&logoColor=white" alt="Python 3.10+"></a>
  <a href="https://github.com/DeHor-Labs/mcp-fiscal-brasil/actions/workflows/ci.yml"><img src="https://github.com/DeHor-Labs/mcp-fiscal-brasil/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
  <a href="LICENSE"><img src="https://img.shields.io/badge/licenca-MIT-FFDF00?labelColor=002776" alt="License MIT"></a>
  <a href="https://modelcontextprotocol.io"><img src="https://img.shields.io/badge/MCP-compatível-7c3aed" alt="MCP Compatible"></a>
  <img src="https://img.shields.io/github/stars/DeHor-Labs/mcp-fiscal-brasil?style=flat&color=009c3b" alt="Stars">
  <img src="https://img.shields.io/github/issues/DeHor-Labs/mcp-fiscal-brasil?color=FFDF00&labelColor=002776" alt="Issues">
</p>

<p align="center">
  <a href="https://dehor-labs.github.io/mcp-fiscal-brasil/">📚 Documentação</a> ·
  <a href="#-instalação">Instalação</a> ·
  <a href="#-ferramentas-disponíveis">Ferramentas</a> ·
  <a href="#-workflows-agênticos">Workflows</a> ·
  <a href="#-roadmap">Roadmap</a> ·
  <a href="#-contribuindo">Contribuindo</a>
</p>

---

## 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](https://render.com/images/deploy-to-render-button.svg)](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

```bash
# 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) |
| 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 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:

```bash
uvx mcp-fiscal-brasil
```

> **O que é `uvx`?** É o gerenciador de ferramentas do [uv](https://docs.astral.sh/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`

---

## ⚙️ 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):

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

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

### Claude Code (CLI)

```bash
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):

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

### VS Code + Continue

Adi