Skip to main content
Glama

Brazil Data MCP

An MCP (Model Context Protocol) server that gives LLM agents access to Brazilian public data: Central Bank series (Selic, IPCA), exchange rates, postal codes (CEP), banks and national holidays.

Status: work in progress. See the roadmap.

Why

Agents that work with Brazilian users constantly need the same public data: "what is the Selic rate today?", "how much is the dollar?", "what address is this CEP?". Each team ends up writing its own wrappers. This project packages those sources as MCP tools, so any MCP client (Claude Desktop, Claude Code, Cursor, custom agents) can use them with no extra code.

Related MCP server: brasilapi-mcp

Architecture

flowchart LR
    A[MCP client<br/>Claude Desktop, Cursor, custom agent] -- stdio / HTTP --> B[Brazil Data MCP server]
    B --> C[BrasilAPI<br/>CEP, banks, holidays]
    B --> D[Banco Central SGS<br/>Selic, IPCA]
    B --> E[Banco Central PTAX<br/>official exchange rates]

Tools

Tool

Description

Source

get_address_by_cep

Address for a Brazilian postal code

BrasilAPI

list_national_holidays

National holidays for a given year

BrasilAPI

get_bank

Bank name and details by bank code

BrasilAPI

get_selic_rate

Latest values of the Selic target rate

BCB SGS (series 432)

get_ipca

Latest monthly IPCA inflation values

BCB SGS (series 433)

get_ptax_rate

Official PTAX USD/BRL rate for a date

BCB PTAX

Getting started

Requires Python 3.11+ and uv.

git clone https://github.com/Mirelasbianchi/brazil-data-mcp.git
cd brazil-data-mcp
uv sync
uv run brazil-data-mcp          # starts the server over stdio
uv run mcp dev src/brazil_data_mcp/server.py   # opens the MCP Inspector

Use with Claude Desktop

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "brazil-data": {
      "command": "uv",
      "args": ["--directory", "/path/to/brazil-data-mcp", "run", "brazil-data-mcp"]
    }
  }
}

Project structure

brazil-data-mcp/
├── src/brazil_data_mcp/
│   ├── server.py      # MCP server and tool definitions
│   └── clients.py     # HTTP clients for BrasilAPI and Banco Central
├── tests/             # unit tests with mocked HTTP
├── .github/workflows/ # CI (lint + tests)
└── pyproject.toml

Roadmap

  • Project skeleton, first tools and CI

  • Error handling and input validation (invalid CEP, future dates, API downtime)

  • Response caching for slow-changing data (holidays, banks)

  • More sources: CNPJ lookup, B3 quotes, IBGE data

  • Streamable HTTP transport for remote use

  • Publish to PyPI and to the MCP server registry

  • Demo video with an agent answering questions using the tools

Development

uv run pytest
uv run ruff check .

License

MIT

Available Tools

6 tools
get_address_by_cepA

Return the address (street, neighborhood, city, state) for a Brazilian CEP.

Args: cep: Postal code with 8 digits, with or without the dash (e.g. "01310-100").

Inputs: cep (required).

get_bankA

Return details of a Brazilian bank by its COMPE code (e.g. 260 for Nubank).

Args: code: Bank code.

Inputs: code (required).

get_ipcaB

Return the latest monthly IPCA inflation values (% per month) from Banco Central.

Args: last: How many months to return (1 to 24).

Inputs: last.

get_ptax_rateA

Return the official PTAX USD/BRL buy and sell rates for a day.

Args: day: Date in YYYY-MM-DD format. Defaults to today. Weekends and holidays have no quote.

Inputs: day.

get_selic_rateA

Return the latest Selic target rate values (% per year) from Banco Central.

Args: last: How many of the most recent values to return (1 to 20).

Inputs: last.

list_national_holidaysA

List Brazilian national holidays for a year.

Args: year: Year between 1900 and 2199.

Inputs: year (required).

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.7/5.0

    Scored across 6 tools

    Disambiguation5/5

    Each tool targets a completely different data domain: address lookup, holidays, bank codes, and three distinct economic indicators (Selic, IPCA, PTAX). There is no plausible way to confuse one tool for another, and the parameter names reinforce the distinction.

    Naming Consistency4/5

    All names are snake_case with a leading verb, which is highly readable. Minor deviation: get_address_by_cep uses a longer prepositional form while every other tool is a simple get_<noun>, and list_national_holidays is the only list_ verb (though this is semantically correct).

    Tool Count5/5

    Six tools is a tight, well-scoped set for a Brazilian reference-data server, with no redundant or filler entries. Each tool maps to one concrete lookup.

    Completeness3/5

    The economic series tools only expose 'most recent N values' — there is no date-range or historical query, and the CEP tool is one-directional (no address-to-CEP). The surface is also a heterogeneous grab bag (postal, calendar, banking, macro), so coverage of any single sub-domain like banking or geography is thin.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      D
      maintenance
      Exposes the BrasilAPI as MCP tools, enabling AI agents to query Brazilian public data such as CEP, CNPJ, DDD, IBGE, banks, PIX, FIPE, NCM, exchange rates, taxes, weather, CVM information, holidays, ISBN, domains, stock tickers, and TUSS.
      41
      Apache 2.0
    • A
      license
      A
      quality
      C
      maintenance
      Enables LLM clients to query public Brazilian data through tools for CEP addresses, CNPJ registrations, banks, FIPE vehicle prices, national holidays, and DDD area codes, with no API key required.
      8
      MIT
    • A
      license
      A
      quality
      C
      maintenance
      Exposes Brazilian public data — postal codes (CEP), company registrations (CNPJ), CPF/CNPJ validation, banks, national holidays, municipalities, and DDD area codes — as MCP tools and resources, backed by BrasilAPI, ViaCEP, and IBGE with caching, fallback, and rate limiting. Any MCP client such as Claude Desktop or Claude Code can query and validate this reference and registration data through natural language or programmatic calls.
      1
      MIT