![Logo](https://s3.devantage.com.br/devantage-public/logo-100x100.png)

# MCP Brazil Public Data

A modern [Model Context Protocol](https://modelcontextprotocol.io) server for
Brazilian public data, backed by [BrasilAPI](https://brasilapi.com.br) — no API key required.
Exposes 15 tools and 2 guided prompts covering companies (CNPJ), postal codes (CEP), banking, economy, geography, and more.

Inspired by the project [`alanpcf/brasil-data-mcp`](https://github.com/alanpcf/brasil-data-mcp), but adding Streamable-HTTP transport.

## Requirements

- Python 3.10+
- [uv](https://github.com/astral-sh/uv) (or Docker, for the containerized setup)

## Installation

```bash
uv venv

uv pip install -e ".[dev]"
```

## Running

The server supports two transports, selected via the `MCP_TRANSPORT` environment variable (see [Configuration](#configuration)).

### STDIO

The server speaks MCP over **stdio** by default (the transport used by most MCP
clients such as Claude Desktop and Claude Code):

```bash
source .venv/bin/activate

mcp-brazil-public-data
```

### Streamable HTTP

To serve over **streamable HTTP** instead:

```bash
source .venv/bin/activate

MCP_TRANSPORT=http mcp-brazil-public-data
```

The HTTP endpoint is then available at `http://0.0.0.0:8080/mcp/`.

### Docker

Build the image and run it in HTTP mode (the image defaults to HTTP on port 8080):

```bash
docker build -t mcp-brazil-public-data .

docker run --rm -p 8080:8080 mcp-brazil-public-data
```

Override any setting at runtime with `-e`, e.g. a different port:

```bash
docker run --rm -p 9000:9000 -e MCP_PORT=9000 mcp-brazil-public-data
```

## Configuration

| Variable        | Default   | Description                                                         |
| --------------- | --------- | ------------------------------------------------------------------- |
| `MCP_TRANSPORT` | `stdio`   | Transport to use: `stdio` or `http` (streamable HTTP).              |
| `MCP_HOST`      | `0.0.0.0` | Host/interface to bind when using HTTP. Use `0.0.0.0` to expose it. |
| `MCP_PORT`      | `8080`    | Port to listen on when using HTTP.                                  |

## Available Tools

### Companies & Finance

| Tool            | Description                                                    | Source          |
| --------------- | -------------------------------------------------------------- | --------------- |
| `lookup_cnpj`   | Company registration data (legal name, status, partners, CNAE) | Federal Revenue |
| `lookup_broker` | CVM-authorized brokerage firm by CNPJ                          | CVM             |
| `list_banks`    | List of ~250 registered banks                                  | BACEN           |
| `get_bank`      | Bank data by COMPE code                                        | BACEN           |

### Location & Geography

| Tool                  | Description                                   | Source          |
| --------------------- | --------------------------------------------- | --------------- |
| `lookup_cep`          | Full address from a postal code (CEP)         | Correios/ViaCEP |
| `lookup_ddd`          | State and cities served by an area code (DDD) | —               |
| `list_states`         | 27 states (UFs) with IBGE codes               | IBGE            |
| `list_municipalities` | Municipalities of a state with IBGE codes     | IBGE            |

### Economy

| Tool                | Description                                 | Source |
| ------------------- | ------------------------------------------- | ------ |
| `list_rates`        | Current economic indices (SELIC, CDI, IPCA) | BACEN  |
| `get_rate`          | Current value of an index by symbol         | BACEN  |
| `list_currencies`   | Foreign currencies available for quotes     | BACEN  |
| `get_exchange_rate` | PTAX quote of a currency on a date          | BACEN  |

### Reference

| Tool              | Description                  | Source           |
| ----------------- | ---------------------------- | ---------------- |
| `list_holidays`   | National holidays for a year | —                |
| `lookup_isbn`     | Book metadata by ISBN        | CBL/Google Books |
| `check_br_domain` | Status of a `.br` domain     | Registro.br      |

### Guided Prompts

| Prompt              | Description                                                |
| ------------------- | ---------------------------------------------------------- |
| `analyze_company`   | Looks up a CNPJ and produces a structured company analysis |
| `economic_overview` | Combines current economic rates with the year's holidays   |

## Development

### Testing

Run the test suite with:

```bash
pytest
```

## License

[MIT](./LICENSE)