MCP Brazil Public Data

A modern Model Context Protocol server for Brazilian public data, backed by BrasilAPI — no API key required. Exposes 15 tools and 2 guided prompts covering companies (CNPJ), postal codes (CEP), banking, economy, geography, and more.

Inspired by the project alanpcf/brasil-data-mcp, but adding Streamable-HTTP transport.

Requirements

• Python 3.10+
• uv (or Docker, for the containerized setup)

Installation

uv venv

uv pip install -e ".[dev]"

Running

The server supports two transports, selected via the MCP_TRANSPORT environment variable (see Configuration).

STDIO

The server speaks MCP over stdio by default (the transport used by most MCP clients such as Claude Desktop and Claude Code):

source .venv/bin/activate

mcp-brazil-public-data

Streamable HTTP

To serve over streamable HTTP instead:

source .venv/bin/activate

MCP_TRANSPORT=http mcp-brazil-public-data

The HTTP endpoint is then available at http://0.0.0.0:8080/mcp/.

Docker

Build the image and run it in HTTP mode (the image defaults to HTTP on port 8080):

docker build -t mcp-brazil-public-data .

docker run --rm -p 8080:8080 mcp-brazil-public-data

Override any setting at runtime with -e, e.g. a different port:

docker run --rm -p 9000:9000 -e MCP_PORT=9000 mcp-brazil-public-data

Configuration

Variable	Default	Description
MCP_TRANSPORT	stdio	Transport to use: stdio or http (streamable HTTP).
MCP_HOST	0.0.0.0	Host/interface to bind when using HTTP. Use 0.0.0.0 to expose it.
MCP_PORT	8080	Port to listen on when using HTTP.

Available Tools

Companies & Finance

Tool	Description	Source
lookup_cnpj	Company registration data (legal name, status, partners, CNAE)	Federal Revenue
lookup_broker	CVM-authorized brokerage firm by CNPJ	CVM
list_banks	List of ~250 registered banks	BACEN
get_bank	Bank data by COMPE code	BACEN

Location & Geography

Tool	Description	Source
lookup_cep	Full address from a postal code (CEP)	Correios/ViaCEP
lookup_ddd	State and cities served by an area code (DDD)	—
list_states	27 states (UFs) with IBGE codes	IBGE
list_municipalities	Municipalities of a state with IBGE codes	IBGE

Economy

Tool	Description	Source
list_rates	Current economic indices (SELIC, CDI, IPCA)	BACEN
get_rate	Current value of an index by symbol	BACEN
list_currencies	Foreign currencies available for quotes	BACEN
get_exchange_rate	PTAX quote of a currency on a date	BACEN

Reference

Tool	Description	Source
list_holidays	National holidays for a year	—
lookup_isbn	Book metadata by ISBN	CBL/Google Books
check_br_domain	Status of a .br domain	Registro.br

Guided Prompts

Prompt	Description
analyze_company	Looks up a CNPJ and produces a structured company analysis
economic_overview	Combines current economic rates with the year's holidays

Development

Testing

Run the test suite with:

pytest

License

MIT