mcp-brasil

MCP (Model Context Protocol) server that exposes Brazilian public data as tools for AI assistants: Claude Desktop, Claude Code, Cursor, and any MCP client.

Available tools

All sources are official open APIs — no API key required, except for INMET hourly data (see below).

Related MCP server: ibge-data-mcp

Installation

Requirements: uv (or Python 3.12+ with pip).

git clone https://github.com/lucianoon/mcp-brasil
cd mcp-brasil
uv sync

Configuration

Claude Desktop / Cursor

Add to the configuration file (claude_desktop_config.json or mcp.json):

{
  "mcpServers": {
    "mcp-brasil": {
      "command": "uv",
      "args": ["run", "--directory", "/caminho/para/mcp-brasil", "mcp-brasil"]
    }
  }
}

Claude Code

claude mcp add mcp-brasil -- uv run --directory /caminho/para/mcp-brasil mcp-brasil

Optional INMET token

Station listing (inmet_estacoes) is open. However, observed hourly data (inmet_dados) requires a token provided by INMET — request it at portal.inmet.gov.br and set the environment variable in the MCP client:

{
  "mcpServers": {
    "mcp-brasil": {
      "command": "uv",
      "args": ["run", "--directory", "/caminho/para/mcp-brasil", "mcp-brasil"],
      "env": { "INMET_TOKEN": "seu-token" }
    }
  }
}

Without the token, the other 13 tools work normally.

Usage examples

After configuring, ask the assistant directly:

• "What was the IPCA for the last 6 months?"

• "What does the market expect for Selic at the next meetings?" (Focus Bulletin)

• "Who are the federal deputies from Minas Gerais of party X?"

• "What is the population of São Paulo in 2022? And the GDP?"

• "How is the PTAX dollar doing in recent days?"

• "Search for 2025 bills on mental health"

• "Which automatic INMET stations exist in Amazonas?"

Development

uv sync --dev
uv run pytest
uv run ruff check .
uv run mypy src

Architecture

src/mcp_brasil/
├── server.py        # Servidor MCP e registro das tools
├── http.py          # Cliente HTTP compartilhado, retry e tratamento de erros
├── cache.py         # Cache TTL em memória para as respostas das APIs
└── tools/
    ├── ibge.py      # SIDRA v3 + localidades v1
    ├── bcb.py       # SGS + Olinda (PTAX e Boletim Focus)
    ├── inmet.py     # Estações e dados observacionais
    └── camara.py    # Dados Abertos da Câmara v2

• stdio transport (MCP desktop standard)

• 10-minute TTL cache per identical request

• Automatic retry on network failures

• Outputs formatted as model-readable text

Roadmap

• v0.2 — INMET (stations + observational with token) and Focus Bulletin

• DOU: search in the Official Gazette of the Union (waiting for a stable public API)

• TSE: election results

• Publication on PyPI (uvx mcp-brasil)

• Optional streamable-http transport

License

MIT