mcp-brasil-public-apis

What this skill does

# mcp-brasil: MCP Server for 28 Brazilian Public APIs

> Skill by [ara.so](https://ara.so) — Daily 2026 Skills collection.

`mcp-brasil` is a [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) 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` in `__init__.py` and `mcp: FastMCP` in `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", ne