# brasilapi-mcp

A [Model Context Protocol](https://modelcontextprotocol.io) (MCP) server I wrote from scratch,
exposing the public [BrasilAPI](https://brasilapi.com.br) as tools an LLM client (Claude Desktop,
Claude Code, or any MCP host) can call. The tools look up a CEP, a CNPJ, banks, FIPE vehicle
prices, national holidays, and DDD area codes.

[README em português](README.pt-BR.md)

## Why this exists

Consuming someone else's MCP server is easy. I wanted to prove I can *build* one, which means
writing the tool schemas and a typed HTTP client behind a boundary that keeps the whole thing
testable. BrasilAPI is a good fit for that. It needs no API key and serves public data, so anyone
can clone this and run it immediately, and every tool is exercised in tests without touching the
network.

## Tools

| Tool | What it returns |
|------|-----------------|
| `cep` | Address for a Brazilian postal code (accepts `01001-000` or `01001000`) |
| `cnpj` | Company registration for a CNPJ (legal name, address, activity, status) |
| `banks` | Every bank registered at the Brazilian Central Bank |
| `bank` | A single bank by its numeric code (e.g. `001`) |
| `holidays` | National holidays for a given year |
| `ddd` | State and cities served by a two-digit phone area code |
| `fipe_brands` | FIPE vehicle brands for `carros`, `motos` or `caminhoes` |
| `fipe_price` | FIPE reference price table for a model code |

## Install

```bash
pip install -e .
```

Dependencies are just `mcp` (the official Python SDK, v2) and `httpx`.

## Run it

```bash
brasilapi-mcp            # runs the MCP server over stdio (what an MCP client launches)
brasilapi-mcp --help     # prints usage and exits, without opening a socket
```

The server speaks MCP over stdio, so you normally don't run it by hand. An MCP client launches it
and talks to it. `python -m brasilapi_mcp.server` works too.

## Wire it into a client

**Claude Desktop.** Add it to `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "brasilapi": {
      "command": "brasilapi-mcp"
    }
  }
}
```

If `brasilapi-mcp` isn't on your PATH, point `command` at your venv's script (e.g.
`.../.venv/Scripts/brasilapi-mcp` on Windows) or use `"command": "python", "args": ["-m",
"brasilapi_mcp.server"]`.

**Claude Code.** One command:

```bash
claude mcp add brasilapi -- brasilapi-mcp
```

Then ask, in plain language: *"what's the address for CEP 01001-000?"* or *"list the national
holidays in 2026"*, and the model will call the matching tool.

## Design: why it tests offline

The network sits behind an injectable boundary. `BrasilAPIClient` takes an optional
`httpx.Client`/transport, so the test suite passes an `httpx.MockTransport` with canned JSON and runs
with no real network I/O. The tool bodies are thin wrappers over plain, synchronous functions that
take the client explicitly, which keeps the logic unit-testable in isolation. A `BrasilAPIError`
becomes a clean message the model can read instead of a traceback.

## Testing

```bash
pip install -e ".[dev]"
pytest -q
```

The suite covers the client against a mock transport, going through every endpoint, the input
normalization and the 404/500 handling. It also covers the tool logic functions and the server's
tool registration. Nothing hits the network.

## A note on the data

BrasilAPI is a public service and needs no key; this server stores no secrets and reads no
environment variables. Live responses are owned by BrasilAPI and its upstream sources.

## License

MIT. See [LICENSE](LICENSE).