mcp-brasil: MCP Server for 28 Brazilian Public APIs Skill by ara.so — Daily 2026 Skills collection. mcp-brasil is a Model Context Protocol (MCP) server that exposes 213 tools, 55 resources, and 45 prompts across 28 Brazilian public APIs — letting AI agents (Claude, GPT, Copilot, Cursor, etc.) query government data in natural language. 26 APIs require no key; only 2 need free registrations. Installation

pip

pip install mcp-brasil

uv (recommended)

uv add mcp-brasil Quick Setup by Client Claude Desktop Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows): { "mcpServers" : { "mcp-brasil" : { "command" : "uvx" , "args" : [ "--from" , "mcp-brasil" , "python" , "-m" , "mcp_brasil.server" ] , "env" : { "TRANSPARENCIA_API_KEY" : "$TRANSPARENCIA_API_KEY" , "DATAJUD_API_KEY" : "$DATAJUD_API_KEY" } } } } VS Code / Cursor Create .vscode/mcp.json in your project root: { "servers" : { "mcp-brasil" : { "command" : "uvx" , "args" : [ "--from" , "mcp-brasil" , "python" , "-m" , "mcp_brasil.server" ] , "env" : { "TRANSPARENCIA_API_KEY" : "$TRANSPARENCIA_API_KEY" , "DATAJUD_API_KEY" : "$DATAJUD_API_KEY" } } } } Claude Code CLI claude mcp add mcp-brasil -- uvx --from mcp-brasil python -m mcp_brasil.server HTTP Transport (other clients) fastmcp run mcp_brasil.server:mcp --transport http --port 8000

Server at http://localhost:8000/mcp

Environment Variables Create a .env file or export in your shell:

Optional — 26 other APIs work without any keys

TRANSPARENCIA_API_KEY

your_key_here

https://portaldatransparencia.gov.br/api-de-dados/cadastrar-email

DATAJUD_API_KEY

your_key_here

https://datajud-wiki.cnj.jus.br/api-publica/acesso

Tuning

MCP_BRASIL_TOOL_SEARCH

bm25

bm25 | code_mode | none (default: bm25)

MCP_BRASIL_HTTP_TIMEOUT

30.0

seconds

MCP_BRASIL_HTTP_MAX_RETRIES

3 API Coverage (28 Features, 213 Tools) Category Feature Key API Tools Economic ibge IBGE — states, municipalities, statistics 9 Economic bacen Banco Central — Selic, IPCA, FX, PIB, 190+ series 9 Legislative camara Câmara dos Deputados — deputies, bills, votes, expenses 10 Legislative senado Senado Federal — senators, bills, votes, committees 26 Transparency transparencia Portal da Transparência — contracts, spending, sanctions 18 Transparency tcu TCU — rulings, ineligible bidders 8 TCE (states) tce_sp/rj/rs/sc/pe/ce/rn/pi/to 9 State audit courts 39 Judiciary datajud DataJud/CNJ — court cases, movements 7 Judiciary jurisprudencia STF, STJ, TST — rulings, precedents 6 Electoral tse TSE — elections, candidates, campaign finance 15 Environment inpe INPE — wildfires, deforestation 4 Environment ana ANA — hydrological stations, reservoirs 3 Health saude CNES/DataSUS — facilities, professionals, beds 4 Oceanography tabua_mares Tide tables for Brazilian ports 7 Procurement pncp PNCP — public contracts (Lei 14.133/2021) 6 Procurement dadosabertos ComprasNet/SIASG 8 Utilities brasilapi CEP, CNPJ, DDD, banks, FX, FIPE, PIX 16 Utilities dados_abertos dados.gov.br — dataset catalog 4 Utilities diario_oficial Official gazettes from 5,000+ cities 4 Utilities transferegov Parliamentary PIX transfers 5 AI Agent redator Draft official documents with real data 5 Meta-Tools (Root Server) Four special tools are always available regardless of feature: Tool Description listar_features List all 28 features with descriptions recomendar_tools BM25 search — get relevant tools for a query planejar_consulta Build multi-API execution plan for a complex query executar_lote Run multiple tool calls in parallel in one request Development Commands git clone https://github.com/jxnxts/mcp-brasil.git cd mcp-brasil make dev

Install all dependencies (prod + dev)

make test

Run all tests

make test-feature F = ibge

Test a single feature

make lint

Lint + format check

make ruff

Auto-fix lint + format

make types

mypy strict mode

make ci

lint + types + test (full CI)

make run

Start server (stdio transport)

make serve

Start server (HTTP :8000)

make inspect

List all tools/resources/prompts

Architecture: Package by Feature + Auto-Registry

src/mcp_brasil/

├── server.py # Auto-discovers features — never edit manually

├── _shared/ # Shared HTTP client, rate limiting, BM25

├── data/ # 27 API features

│ ├── ibge/

│ │ ├── init.py # exports FEATURE_META

│ │ ├── server.py # FastMCP instance (exports mcp)

│ │ ├── tools.py # Tool implementations

│ │ ├── client.py # Async HTTP via httpx

│ │ ├── schemas.py # Pydantic v2 models

│ │ └── constants.py # Base URLs, codes

│ ├── bacen/

│ └── ...

└── agentes/ # Intelligent agent features

└── redator/

Auto-registry

The root server.py scans for FEATURE_META in init.py and mcp: FastMCP in server.py — no manual registration needed. Adding a New Feature mkdir src/mcp_brasil/data/myfeature touch src/mcp_brasil/data/myfeature/ { init.py,server.py,tools.py,client.py,schemas.py,constants.py } init.py — Required export from mcp_brasil . _shared . types import FeatureMeta FEATURE_META = FeatureMeta ( name = "myfeature" , description = "Short description of the API" , tags = [ "category" ] , requires_key = False , ) server.py — Required export from fastmcp import FastMCP from . tools import register_tools mcp = FastMCP ( "myfeature" ) register_tools ( mcp ) client.py — Async HTTP pattern import httpx from mcp_brasil . _shared . http import get_client BASE_URL = "https://api.example.gov.br" async def fetch_data ( endpoint : str , params : dict ) -

dict : async with get_client ( ) as client : response = await client . get ( f" { BASE_URL } / { endpoint } " , params = params ) response . raise_for_status ( ) return response . json ( ) schemas.py — Pydantic v2 models from pydantic import BaseModel , Field from typing import Optional class MyResult ( BaseModel ) : id : str name : str value : Optional [ float ] = Field ( None , description = "Numeric value" ) tools.py — Tool registration from fastmcp import FastMCP from . client import fetch_data from . schemas import MyResult def register_tools ( mcp : FastMCP ) -

None : @mcp . tool ( description = "Busca dados do endpoint X" ) async def buscar_dados ( codigo : str , ano : int = 2024 , ) -

list [ MyResult ] : """Retorna dados do endpoint X para o código fornecido.""" raw = await fetch_data ( "endpoint-x" , { "codigo" : codigo , "ano" : ano } ) return [ MyResult ( ** item ) for item in raw . get ( "data" , [ ] ) ] tests/data/myfeature/test_tools.py — Test pattern import pytest from unittest . mock import AsyncMock , patch from mcp_brasil . data . myfeature . tools import register_tools from fastmcp import FastMCP @pytest . fixture def mcp ( ) : server = FastMCP ( "test-myfeature" ) register_tools ( server ) return server @pytest . mark . asyncio async def test_buscar_dados ( mcp ) : mock_response = { "data" : [ { "id" : "001" , "name" : "Test" , "value" : 42.0 } ] } with patch ( "mcp_brasil.data.myfeature.client.fetch_data" , new_callable = AsyncMock ) as mock : mock . return_value = mock_response

call via mcp tool invocation or directly

from mcp_brasil . data . myfeature . tools import buscar_dados result = await buscar_dados ( codigo = "001" ) assert len ( result ) == 1 assert result [ 0 ] . name == "Test" Common Usage Patterns Pattern 1: Cross-reference with planejar_consulta Ask the agent to plan a multi-API query: "Crie um plano de consulta para analisar o deputado federal João Silva: gastos, votações, proposições e financiamento de campanha." The planejar_consulta meta-tool returns a structured execution plan combining camara , tse , and transparencia tools. Pattern 2: Parallel execution with executar_lote "Execute em paralelo: taxa Selic atual, IPCA dos últimos 12 meses, e câmbio USD/BRL de hoje." executar_lote fires all three bacen tool calls concurrently. Pattern 3: Smart discovery with recomendar_tools "Quais tools devo usar para investigar contratos suspeitos em licitações municipais?" BM25 search filters the 213 tools to return only relevant ones (e.g., tce_sp , pncp , tcu , transparencia ). Pattern 4: Direct tool calls in code import asyncio from mcp_brasil . data . bacen . tools import buscar_serie_temporal from mcp_brasil . data . ibge . tools import buscar_municipios async def main ( ) :

Selic rate last 12 months

selic

await buscar_serie_temporal ( codigo = "432" , ultimos = 12 )

All municipalities in São Paulo state

municipios

await buscar_municipios ( uf = "SP" ) print ( f"Selic entries: { len ( selic ) } " ) print ( f"SP municipalities: { len ( municipios ) } " ) asyncio . run ( main ( ) ) Pattern 5: Using brasilapi for CNPJ/CEP lookup from mcp_brasil . data . brasilapi . tools import consultar_cnpj , consultar_cep async def lookup ( ) : empresa = await consultar_cnpj ( cnpj = "00000000000191" )

Banco do Brasil

endereco

await consultar_cep ( cep = "01310100" )

Av. Paulista

Natural Language Query Examples Once the server is connected to your AI client:

Economic analysis

"Qual a tendência da taxa Selic nos últimos 12 meses? Compare com IPCA."

Legislative research

"Quais projetos de lei sobre IA tramitaram na Câmara em 2024? Quem foram os autores?"

Transparency / anti-corruption

"Quais os 10 maiores contratos do governo federal em 2024?"

Cross-state comparison

"Compare gastos per capita com saúde em SP e MG cruzando TCE-SP e IBGE."

Judiciary

"Busque processos sobre licitação irregular no TCU. Quais as penalidades?"

Electoral finance

"Quais os maiores doadores da campanha do candidato X?"

Environment

"Quantos focos de queimada foram registrados no Cerrado em agosto 2024?"

Document generation (redator feature)

"Redija um ofício solicitando informações sobre o contrato 001/2024 com dados reais do Portal da Transparência." Troubleshooting Server not starting

Verify installation

python -m mcp_brasil.server --help

Check uvx finds the package

uvx --from mcp-brasil python -c "import mcp_brasil; print(mcp_brasil.version)" API returning 401/403 transparencia and datajud silently degrade without keys — set TRANSPARENCIA_API_KEY and DATAJUD_API_KEY for full access Keys are free: Transparência | DataJud Too many tools visible (context overflow) Set MCP_BRASIL_TOOL_SEARCH=bm25 (default) — only tools relevant to the current query are surfaced. Use code_mode to expose all tools, or none to disable filtering. Timeout errors on slow government APIs MCP_BRASIL_HTTP_TIMEOUT = 60.0

increase timeout

MCP_BRASIL_HTTP_MAX_RETRIES

5

increase retries

Feature not auto-discovered Ensure your feature folder exports both: FEATURE_META in init.py mcp: FastMCP instance in server.py Run make inspect to verify your feature appears in the tool list. Running tests for a specific feature make test-feature F = bacen make test-feature F = transparencia Key Design Principles Async everywhere — httpx async client, all tools are async def Pydantic v2 — all API responses validated through typed schemas Rate limiting with backoff — built into _shared/http.py , transparent to feature code Zero manual registration — add a folder → it's discovered automatically BM25 smart filtering — prevents context window bloat from 213 tools Graceful degradation — APIs requiring keys still work (with reduced limits) without them