PluginBench
MCP Server
Active
MIT

MCP Fiscal Brasil MCP Server

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

Brazilian fiscal tools for CNPJ, NF-e, SPED, eSocial, Simples Nacional and Tax Reform 2026 – no API keys required.

What is the MCP Fiscal Brasil MCP server?

MCP Fiscal Brasil is a Model Context Protocol server that provides native support for Brazilian fiscal documents and compliance data including NF-e, NFS-e, SPED, eSocial, Simples Nacional, and the 2026 Tax Reform (IBS/CBS). It requires no API keys, accounts, or configuration and works entirely offline for parsing, validation, and analysis tasks.

MCP Fiscal Brasil connects AI assistants, ERPs, and CRMs to Brazil's complex fiscal ecosystem. It offers both low-level tools for parsing and validating fiscal documents (NF-e XML, SPED files, CPF/CNPJ) and high-level agentic tools for compliance analysis, supplier risk scoring, and tax regime comparison. All core functionality works without external API keys or authentication.

How to install MCP Fiscal Brasil

Copy-paste configuration for popular MCP clients.

transport: stdio
Config generated by PluginBench — verify against the source before use.
~/Library/Application Support/Claude/claude_desktop_config.json
{
  "mcpServers": {
    "mcp-fiscal-brasil": {
      "command": "uvx",
      "args": [
        "mcp-fiscal-brasil"
      ]
    }
  }
}

Tools & capabilities

Tools this server exposes to the agent.

  • analyze_cnpj_compliance — Consolidated compliance report for a CNPJ including Simples Nacional status, CNAE, and risk factors
  • risk_score_supplier — Supplier risk scoring (0-100) with recommendation to approve, investigate, or reject
  • consultar_empresas_lote — Batch query of multiple CNPJs with compliance and risk score per company
  • compare_tax_regimes — Compare tax regimes (MEI, Simples, Lucro Presumido, Lucro Real) by scenario
  • validate_nfe_full — Full NF-e validation from XML including signature, structure, and issuer verification
  • summarize_sped — Transform SPED file into executive summary with period, company, blocks, and inconsistencies
  • consultar_cnpj — Complete CNPJ data: legal name, partners, CNAE, address via BrasilAPI
  • consultar_simples_nacional — Check if CNPJ is enrolled in Simples Nacional/MEI with entry and exit dates
  • validar_chave_nfe — Validate NF-e key (44 digits) and extract UF, CNPJ, date, number
  • consultar_nfe — Query complete NF-e by 44-digit key via BrasilAPI
  • parse_nfe_xml — Parse raw NF-e/NFC-e XML and return structured data
  • gerar_danfe — Generate DANFE PDF (A4) from NF-e XML (mod 55)
  • validar_assinatura_nfe — Validate XMLDSig signature and extract certificate data
  • consultar_status_sefaz — Real-time SEFAZ webservice status by state (requires A1 certificate)
  • baixar_nfe_distribuicao — Download documents via NFeDistribuicaoDFe (requires local A1 certificate)
  • manifestar_nfe — Manifest recipient in NF-e via NFeRecepcaoEvento (requires A1 certificate)
  • validar_cpf — CPF check digit validation
  • analisar_sped — Analyze EFD/ECD/ECF file: period, company, errors
  • listar_registros_sped — Filter SPED records by type (C100, E110, etc.)
  • listar_eventos_esocial — Filterable catalog of eSocial events by group

Use cases

  • Perform supplier due diligence by scoring CNPJ risk (0-100) with compliance factors and hiring recommendation
  • Validate NF-e XML files offline: check signature, structure, issuer CNPJ, and generate DANFE PDF
  • Analyze SPED fiscal files to extract period, company, blocks, and identify inconsistencies without manual review
  • Compare tax regimes (MEI, Simples, Lucro Presumido, Lucro Real) for a given revenue and payroll scenario
  • Batch-screen supplier portfolios by CNPJ with compliance status and risk score in a single call
  • Check Simples Nacional enrollment status and dates for a CNPJ to verify tax regime eligibility

MCP Fiscal Brasil MCP server FAQ

What is MCP Fiscal Brasil?

MCP Fiscal Brasil is a Model Context Protocol server that provides Brazilian fiscal tools for CNPJ, NF-e, SPED, eSocial, Simples Nacional, and 2026 Tax Reform compliance. It works offline for parsing and validation, and connects to public APIs (BrasilAPI, SEFAZ) for real-time data—all without requiring API keys.

Do I need an API key or account?

No. Core tools work entirely offline (XML parsing, validation, CPF/CNPJ digit checks). Queries to public data (CNPJ details, NF-e lookup) use free BrasilAPI. Optional SEFAZ features (status check, document download, manifestation) require a local A1 digital certificate, but no external account.

How do I install it in Claude Desktop or Cursor?

For Claude Desktop: edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows) and add {"fiscal-brasil": {"command": "uvx", "args": ["mcp-fiscal-brasil"]}}. For Cursor: create .cursor/mcp.json with the same config. Restart the app; tools appear automatically.

Is it free?

Yes. The server itself is free (MIT license, open-source). It uses free public APIs (BrasilAPI, SEFAZ webservices). Optional features requiring an A1 certificate (SEFAZ status, document download) have no additional cost—you only need the certificate you may already have for fiscal operations.

What Python version is required?

Python 3.10 or higher. Install via `pip install mcp-fiscal-brasil` or run instantly with `uvx mcp-fiscal-brasil` (no permanent installation needed).

Can I use it offline?

Partially. Parsing NF-e XML, validating signatures, analyzing SPED files, and checking CPF/CNPJ digits all work offline. Queries to CNPJ details, NF-e lookup, and SEFAZ status require internet. The server gracefully handles network failures and caches results.

README (reference)

Source of truth, from the repository.

<!-- mcp-name: io.github.DeHor-Labs/mcp-fiscal-brasil --> <p align="center"> <img src="https://raw.githubusercontent.com/DeHor-Labs/mcp-fiscal-brasil/main/assets/banner.svg" width="800" alt="MCP Fiscal Brasil"> </p> <p align="center"> <strong>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.</strong> </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://pypi.org/project/mcp-fiscal-brasil/"><img src="https://img.shields.io/pypi/dm/mcp-fiscal-brasil?color=009c3b&label=downloads%2Fm%C3%AAs" alt="PyPI downloads"></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> <img src="https://img.shields.io/badge/cobertura-85%25-009c3b?labelColor=002776" alt="Cobertura de testes 85%"> <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-que-vendem-sozinho">Workflows</a> · <a href="#-roadmap">Roadmap</a> · <a href="#-contribuindo">Contribuindo</a> </p>

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?

Funcionalidademcp-fiscal-brasilmcp-brasilbrasil-data-mcp
FocoVertical fiscal profundaDados públicos geraisDados públicos gerais
NF-e: parse, validação, DANFE, assinaturaSimNãoNão
SPED/eSocial: análise offlineSimNãoNão
Tabelas offline (NCM, CFOP, CNAE)SimNãoNão
Reforma Tributária 2026 (IBS/CBS)SimNãoNão
Simples Nacional/MEISimNãoNão
Certidão federal/FGTSSim (orientação)NãoNão
Certificado A1 (mTLS SEFAZ)Sim (opt-in)NãoNão
Zero-cadastro, zero chave obrigatóriaSimParcial (3 APIs exigem chave)Sim
Tools agênticas de alto nívelSim (6 tools)ParcialNão
Linguagem de implementaçãoPythonPythonNode.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

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_nfeConsulta NFe completa pela chave de 44 dígitosBrasilAPI (grátis)
NFeparse_nfe_xmlParseia XML bruto de NF-e/NFC-e e retorna dados estruturadosOffline
NFegerar_danfeGera DANFE PDF (A4) a partir do XML de NF-e (mod 55)Offline
NFevalidar_assinatura_nfeValida assinatura XMLDSig e extrai dados do certificadoOffline
NFeconsultar_status_sefazStatus real do webservice SEFAZ por estado via NfeStatusServico4 (requer cert A1)SEFAZ (mTLS)
NFebaixar_nfe_distribuicaoBaixa documentos via NFeDistribuicaoDFe (requer cert A1 local)SEFAZ (mTLS)
NFemanifestar_nfeManifesta destinatario em NF-e via NFeRecepcaoEvento (requer cert A1)SEFAZ (mTLS)
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 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ávelDescrição
NFE_CERTIFICADO_PATHCaminho absoluto do .pfx/.p12 montado no container
NFE_CERTIFICADO_SENHASenha do certificado (sempre via gestor de segredos, nunca em .env versionado)
NFE_EMITENTE_CNPJCNPJ do titular do certificado (14 dígitos, opcional)
NFE_AMBIENTEproducao 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óduloFerramentaLimitação
CNPJlistar_cnpjs_por_nomeReceita 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á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 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; ~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

GitHub Discussions GitHub Stars

<a href="https://star-history.com/#DeHor-Labs/mcp-fiscal-brasil&Date"> <picture> <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/svg?repos=DeHor-Labs/mcp-fiscal-brasil&type=Date&theme=dark" /> <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/svg?repos=DeHor-Labs/mcp-fiscal-brasil&type=Date" /> <img alt="Star History Chart" src="https://api.star-history.com/svg?repos=DeHor-Labs/mcp-fiscal-brasil&type=Date" /> </picture> </a>
  • 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.


<p align="center"> Feito com 💚💛 para o Brasil <br> <sub>Conectando inteligência artificial ao sistema fiscal mais complexo do mundo</sub> </p>

Related MCP servers

Browse, search and fuzzy-match NACE Rev. 2.1 economic activity classification codes.

0
JavaScript
MIT
View repository →
DEDealMachine logo

Search and enrich US property, owner, people, and company data for sales and lead generation.

0
TypeScript
MIT
View repository →

HTTP API layer for LLMs—make requests, manage secrets, and auto-generate tools from OpenAPI specs.

38
JavaScript
MIT
View repository →

Pseudonymizes PII before your LLM and returns a cryptographically signed receipt per response.

1
TypeScript
MIT
View repository →

Web scraping API for AI agents—scrape dynamic sites, search engines, and eCommerce without building infrastructure.

29
TypeScript
View repository →

An MCP Server that provides identity verification and anti-fraud tools for AI agents via deepidv.

2
Shell
Apache-2.0
View repository →