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

bash

# 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):

json

{
  "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:

json

{
  "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

bash

claude mcp add mcp-brasil -- uvx --from mcp-brasil python -m mcp_brasil.server

HTTP Transport (other clients)

bash

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:

bash

# 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

bash

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

__init__.py

and

mcp: FastMCP

server.py

— no manual registration needed.

Adding a New Feature

bash

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

python

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

python

from fastmcp import FastMCP
from .tools import register_tools

mcp = FastMCP("myfeature")
register_tools(mcp)

client.py

— Async HTTP pattern

python

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

python

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

python

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

python

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

python

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

python

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

bash

# 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

bash

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

bash

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

mcp-brasil-public-apis

NPX Install

Tags

SKILL.md Content

mcp-brasil: MCP Server for 28 Brazilian Public APIs

Installation

Quick Setup by Client

Claude Desktop

VS Code / Cursor

Claude Code CLI

HTTP Transport (other clients)

Environment Variables

API Coverage (28 Features, 213 Tools)

Meta-Tools (Root Server)

Development Commands

Architecture: Package by Feature + Auto-Registry

Adding a New Feature

`init.py`
— Required export

`server.py`
— Required export

`client.py`
— Async HTTP pattern

`schemas.py`
— Pydantic v2 models

`tools.py`
— Tool registration

`tests/data/myfeature/test_tools.py`
— Test pattern

Common Usage Patterns

Pattern 1: Cross-reference with
`planejar_consulta`

Pattern 2: Parallel execution with
`executar_lote`

Pattern 3: Smart discovery with
`recomendar_tools`

Pattern 4: Direct tool calls in code

Pattern 5: Using brasilapi for CNPJ/CEP lookup

Natural Language Query Examples

Troubleshooting

Server not starting

API returning 401/403

Too many tools visible (context overflow)

Timeout errors on slow government APIs

Feature not auto-discovered

Running tests for a specific feature

Key Design Principles