mcp-fiscal-brasil: a fiscal MCP server for Brazilian tax data

What mcp-fiscal-brasil solves, and for whom

Brazilian fiscal integration is fragmented by design. The README counts 27 state SEFAZs, separate NF-e, NFS-e, SPED and eSocial flows, and thousands of municipal portals, each with its own rules. An AI assistant asked a tax question has no single endpoint to call. mcp-fiscal-brasil exists to be that endpoint: a Model Context Protocol server that exposes fiscal operations as tools an LLM can invoke.

The audience is narrow on purpose. The README states the project is not a general public-data catalogue, unlike mcp-brasil and brasil-data-mcp, which cover CEP, banks, holidays and economics. This one is a vertical: XML parsing, XSD validation, embedded NCM/CFOP/CNAE tables, Simples Nacional, and IBS/CBS support for the 2026 reform. If you are building an ERP assistant, a supplier onboarding flow, or an accounting copilot, that is the intended use. If you want a CEP lookup, this is the wrong project.

How the server is put together: MCP tools over offline tables and HTTP clients

The architecture visible in the repository is a Python package built on fastmcp, with pydantic models, lxml for XML work, httpx for outbound calls, tenacity for retries, cachetools for caching and aiolimiter for per-host rate limiting. The README describes an HTTP client layer with exponential retry, a pluggable cache and structured JSON logs, which is the part that talks to external sources such as Receita Federal or IBGE.

On top of that sit 44 tools. Six are described as higher-level agentic tools meant to be called by a model rather than a script: risk_score_supplier, consultar_empresas_lote, analyze_cnpj_compliance, validate_nfe_full, summarize_sped and compare_tax_regimes. The pattern is that a single tool call returns a structured judgement, such as a 0 to 100 supplier risk score with factors and a hiring recommendation, instead of raw fields the model must interpret.

The offline side matters as much as the network side. Reference tables for NCM, CFOP and CNAE ship with the package, so classification lookups do not depend on an external service. NF-e parsing, XSD validation and DANFE generation are local operations. The README also notes an opt-in A1 certificate path for mTLS against SEFAZ, which is the only feature that requires a credential.

Installing mcp-fiscal-brasil and running a first CNPJ lookup

The README's quick start is a single uvx command. It runs the MCP server over stdio, which is the transport local AI clients use.

uvx mcp-fiscal-brasil

The README warns that uvx caches the installed version, so pin or refresh explicitly if you want the newest release from PyPI.

uvx mcp-fiscal-brasil@latest
uvx --refresh mcp-fiscal-brasil

To wire it into Claude Desktop, edit the client config at ~/Library/Application Support/Claude/claude_desktop_config.json on macOS or %APPDATA%\Claude\claude_desktop_config.json on Windows, adding an entry under mcpServers.

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

After restarting Claude Desktop, the README says the fiscal tools appear automatically with no API key. For a first real use outside an MCP client, the package also ships a CLI. The README gives these examples, including a CNPJ lookup and a tax regime comparison that takes revenue, sector and payroll.

mcp-fiscal cnpj 12345678000190
mcp-fiscal compliance 12345678000190
mcp-fiscal regimes --faturamento 500000 --setor serviços --folha 180000

There is also a REST API and web UI demo, started with mcp-fiscal-api and listening on http://localhost:8000 by default. Docker users can run docker compose up api from the repository root, which maps port 8000 and sets MCP_FISCAL_HTTP_TIMEOUT, MCP_FISCAL_CACHE_TTL and MCP_FISCAL_RATE_LIMIT. The .env.example file is explicit that no environment variable is required in stdio mode; FASTMCP_TRANSPORT, PORT and HOST only matter for HTTP or SSE deployments.

Where mcp-fiscal-brasil stops: certificates, beta status and unverified claims

The clearest limitation is documented in .env.example. Without an A1 e-CNPJ certificate, the endpoint GET /v1/nfe/status-sefaz returns HTTP 503, because querying real SEFAZ status uses mTLS and requires the certificate. The README lists the A1 certificate as opt-in, which is accurate for everything else, but anyone expecting live SEFAZ status out of the box will hit that wall. The same file warns against putting NFE_CERTIFICADO_SENHA in a versioned .env or a shared environment, and recommends mounting it as a secret file in Cloud Run or Fly.io.

The second constraint is maturity. pyproject.toml declares Development Status 4 - Beta at version 0.5.1, and the release history shows 0.4.0 and 0.5.0 arriving within days of each other in June 2026. Tool names and output schemas are the kind of surface that moves in a beta. Pinning a version is not paranoia here.

The third is the README itself. Its headline calls this the only MCP server with native support for NF-e, NFS-e, SPED, eSocial, Simples Nacional and Reforma 2026, and the comparison table marks every feature as present. Those are the project's own claims, and the README does not document how each data source is kept current, how often the embedded NCM/CFOP/CNAE tables are refreshed, or what happens when a SEFAZ schema changes. The test coverage badge claims 85%, but coverage is not the same as correctness against production fiscal documents. Treat the offline parsing as the part you can verify locally and the network-backed tools as the part you should test against your own cases.

mcp-brasil and brasil-data-mcp: general public data versus a fiscal vertical

The README positions this project against mcp-brasil and brasil-data-mcp, and the difference is scope rather than quality. Those two cover general Brazilian public data: CEP, banks, holidays, economics. mcp-brasil is written in Python, brasil-data-mcp in Node.js, and the README notes that three of mcp-brasil's APIs require a key while this project requires none.

The practical consequence is what you can build. With a general data server, an agent can answer "what is the CEP of this address" or "what is today's holiday". It cannot parse an NF-e XML, validate it against a schema, generate a DANFE, or summarize a SPED file. Those operations need domain-specific parsing and reference tables, which is what the 44 tools here provide. Conversely, if your task is address normalization, pulling in a fiscal vertical adds a dependency you will not use.

The two categories are complementary. A serious Brazilian business assistant could register both servers and let the model choose. Nothing in the README suggests they conflict.

Licence, maintenance and upgrade cost

The licence is MIT, declared both in pyproject.toml and in the LICENSE file, and the README badge repeats it. For most teams that means permissive use, modification and redistribution, with the usual requirement to keep the copyright notice. This is not legal advice; if you embed the package in a product, have counsel confirm how the bundled brazilfiscalreport dependency and any embedded reference tables are licensed, because those are separate works with their own terms.

Maintenance looks current. The last push was on 2026-09-13, two days before this writing, and the repository is not archived. The most recent tagged release is v0.5.1 from 2026-06-21, so there is a gap between commits and releases that is worth noting if you depend on tags rather than the main branch.

Upgrade cost is concentrated in two places. First, the tool surface: 44 tools with structured outputs means a schema change can break an agent prompt or a downstream parser. Second, the transport story: stdio, sse, http and streamable-http are all supported, and the Docker image's healthcheck script auto-detects which mode is running, so a deployment change can shift behaviour without a code change on your side. The CHANGELOG.md and the release-please configuration in the repository are the places to read before bumping a pinned version.

Editorial conclusion

Adopt it if you are building an LLM or agent workflow over Brazilian fiscal documents and want offline parsing, embedded reference tables and no API keys. Skip it if you need real SEFAZ status queries without an A1 certificate, or if you expect a stable 1.0 API. Before adopting, check the CHANGELOG and the docs/getting-started/deploy.md deployment notes for the version you pin.

Frequently asked questions

Official sources

1. DeHor-Labs/mcp-fiscal-brasil on GitHub
2. License: MIT
3. Project website
4. README
5. Releases