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 ```bash 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](https://pypi.org/project/mcp-fiscal-brasil/). ### 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 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 ```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_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 | `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. --- ### 🧪 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` > **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): ```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 Adicione ao `settings.json`: ```json { "continue.mcpServers": { "fiscal-brasil": { "command": "uvx", "args": ["mcp-fiscal-brasil"] } } } ``` ### Docker ```bash 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? ```bash # 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 ```bash 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 ```python 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) ```python 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 ```python 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 ```python # 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) ```python 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 ```python 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](https://brasilapi.com.br) - CNPJ, CEP, bancos (open source, sem autenticação) - [ReceitaWS](https://www.receitaws.com.br) - CNPJ (fallback) - SEFAZs estaduais - Status de serviço e consulta de NFe - Receita Federal - Simples Nacional e certidões (orientação de acesso) --- ## 📍 Roadmap - [x] **v0.1.x** - Consultas CNPJ, CPF, NFe, Simples Nacional e SPED; ~14 tools MCP - [x] **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 - [x] **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 - [x] **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 - [x] **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; ~44 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 [](https://github.com/DeHor-Labs/mcp-fiscal-brasil/discussions) [](https://github.com/DeHor-Labs/mcp-fiscal-brasil/stargazers)
Feito com 💚💛 para o Brasil
Conectando inteligência artificial ao sistema fiscal mais complexo do mundo