mcp-server-brasil

A Model Context Protocol server that gives LLM agents reliable access to Brazilian public data: addresses by CEP, company records by CNPJ, holidays and business days, Banco Central indicators and IBGE municipalities.

🇧🇷 Servidor MCP com dados públicos do Brasil para agentes de IA: CEP, CNPJ (inclusive o alfanumérico), feriados, dias úteis, Selic/IPCA/dólar do Banco Central e municípios do IBGE.

Why

Agents keep getting Brazilian data wrong: they invent CEPs, can't count business days around Carnaval and don't know the current Selic. This server turns the official public sources into typed, validated tools, so the model asks instead of guessing.

• Validates before calling the network. CPF/CNPJ check digits and CEP shape are checked locally, so a hallucinated document never becomes an HTTP request.

• Ready for the alphanumeric CNPJ (IN RFB 2.229/2024, in effect since July 2026).

• Structured output. Every tool returns a JSON schema'd result, with errors reported as tool errors the model can read and recover from.

• A good citizen of free APIs. TTL cache, timeouts and retry with backoff for 5xx only.

• stdio and Streamable HTTP transports, Docker image with healthcheck and DNS rebinding protection for public deployments.

Related MCP server: MCP Brazil Public Data

Tools

It also exposes the resource brasil://indicadores (indicator catalog with SGS codes) and the prompt resumo_macro (rates, inflation and FX summary).

Quickstart

Claude Code

claude mcp add brasil -- uvx mcp-server-brasil

Claude Desktop / Cursor / any MCP client

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

Hosted (Streamable HTTP)

A public instance runs at https://mcp.vgmelo.tech/mcp:

claude mcp add --transport http brasil https://mcp.vgmelo.tech/mcp

Docker

docker run --rm -p 8000:8000 -e MCP_ALLOWED_HOSTS=localhost:8000 ghcr.io/vicgamelo/mcp-server-brasil
curl localhost:8000/health

Example

You: How many business days are there in November 2026, and what's the Selic rate today?

Agent → dias_uteis(inicio="2026-11-01", fim="2026-11-30") → 19, excluding Finados (11/02) and Consciência Negra (11/20) → indicador_economico(indicador="selic_meta", ultimos=1) → 13.75% a.a.

Development

uv sync
uv run pytest          # in-process MCP client + mocked HTTP, no network needed
uv run ruff check . && uv run mypy
uv run mcp-server-brasil --http --port 8000

Tests run a real MCP Client against the server in-process, with the public APIs replaced by httpx.MockTransport, so they cover the protocol layer, input validation, caching and retry behavior without hitting the network.

Project layout

src/mcp_server_brasil/
├── server.py         # MCP tools, resource and prompt
├── sources.py        # BrasilAPI / BCB / IBGE clients with cache + retry
├── documents.py      # CPF, CNPJ (alphanumeric) and CEP validation
├── business_days.py  # business-day arithmetic
└── __main__.py       # CLI: stdio or Streamable HTTP

Roadmap

• State and municipal holidays

• PIX key format validation

• FIPE vehicle prices

• Optional Redis cache for multi-replica deployments

License

MIT © Victor Gabriel Andrade de Melo