mcp‑fiscal‑brasil – Fiscal data server for AI agents

What it is – A Python‑based MCP (Model Context Protocol) server that gives AI assistants, ERPs, CRMs and other automation tools instant, offline‑first access to Brazil’s complex fiscal ecosystem (CNPJ/CPF, NF‑e, NF‑Se, SPED, eSocial, Simples Nacional, the 2026 tax reform, etc.). No API keys or prior registration are required for the core features.

---

Core capabilities

Area	Tools (high‑level)	Low‑level primitives
Company compliance	analyze_cnpj_compliance, risk_score_supplier, consultar_empresas_lote	consultar_cnpj, consultar_simples_nacional
Tax‑regime planning	compare_tax_regimes	–
Invoice handling	validate_nfe_full, summarize_sped	validar_chave_nfe, parse_nfe_xml, gerar_danfe, validar_assinatura_nfe
Public‑service status	–	consultar_status_sefaz
Guidance	–	consultar_nfse, consultar_certidao_federal, consultar_certidao_fgts

All tools work without any API key; optional premium sources (cpfcnpj.com.br) can be enabled via a token for richer, real‑time data.

---

How it works

1. Run the MCP server (or the CLI / REST API) – e.g. uvx mcp-fiscal-brasil.
2. Configure your AI client (Claude Desktop, Cursor, VS Code Continue, etc.) to point to the fiscal-brasil server.
3. Ask natural‑language questions; the server translates them into the appropriate low‑level calls, aggregates data from public APIs (BrasilAPI, Receita WS) and, when needed, performs offline XML parsing or mTLS calls to SEFAZ.
4. The response is returned as structured JSON that the AI can directly use.

---

Installation & quick start

# One‑off execution (no permanent install)
uvx mcp-fiscal-brasil

# Keep it up‑to‑date
uvx mcp-fiscal-brasil@latest   # or uvx --refresh …

Alternatively install via pip/uv or run the Docker image ghcr.io/dehor-labs/mcp-fiscal-brasil:latest.

---

Example interactions

You:  Consulte o CNPJ 00.000.000/0001-91 e liste os sócios.
AI:  Empresa: Banco do Brasil S.A.
     Sócios: União Federal (60,82%), BNDESPar (10,32%) …

You:  A chave NFe 35240300623904000197550010000012341234567890 é válida?
AI:  Chave válida! UF=SP, Emissão=03/2024, CNPJ emissor=00.623.904/0001-97

You:  Qual regime tributário seria mais vantajoso para faturamento 500 k no setor de serviços?
AI:  Compare_tax_regimes → Simples Nacional yields lowest tax (≈ 12 %).

These demos are powered by the high‑level tools consultar_cnpj, validar_chave_nfe, and compare_tax_regimes.

---

Optional premium source

Set CPFCNPJ_TOKEN (and related env vars) to enable the cpfcnpj.com.br API, which adds:

• Real‑time official data (no lag)
• Full NF‑e/NFC‑e lookup by key
• Higher‑grade compliance data The server falls back to free sources when the token is absent, so the base product remains free.

---

Who should use it

• AI‑assistant developers who need a ready‑made fiscal knowledge base for Brazilian clients.
• ERP/CRM integrators looking to add tax‑compliance checks without writing custom SEFAZ connectors.
• Compliance teams that want quick risk scores or batch CNPJ vetting.
• Developers who prefer a single Python package rather than juggling dozens of public APIs.

---

Roadmap highlights

• Expand coverage of municipal NF‑Se portals.
• Add more experimental tools (e.g., name‑based CNPJ search).
• Provide a fully typed OpenAPI spec for the REST interface.
• Improve caching strategies and add a Redis‑backed plug‑in.

---

License & community

• MIT License – free for commercial and non‑commercial use.
• Actively maintained (CI badge, test coverage ≈ 85 %).
• Contributions welcomed via the usual GitHub pull‑request workflow.

---

Bottom line: mcp-fiscal-brasil is a turnkey, zero‑configuration server that turns Brazil’s notoriously fragmented fiscal data into a clean, agent‑friendly API, enabling AI assistants to answer tax‑related queries out‑of‑the‑box.