# mcp-brasil-data

An [MCP](https://modelcontextprotocol.io) server that gives AI assistants (Claude Desktop, Claude Code, Cursor and any MCP client) access to **Brazilian public data**: postal codes, company registry, national holidays, business-day math and official exchange rates.

## Tools

| Tool | What it does | Source |
| --- | --- | --- |
| `lookup_cep` | Address for a CEP (postal code) | ViaCEP |
| `validate_cnpj` | Offline check-digit validation, including the new **alphanumeric CNPJ** format | — |
| `lookup_cnpj` | Public company data: legal name, status, main activity (CNAE), location | BrasilAPI |
| `list_holidays` | National holidays for a year | BrasilAPI |
| `business_days_between` | Business days between two dates, excluding weekends and national holidays | BrasilAPI |
| `get_ptax_rate` | Official PTAX rate (BRL per unit) for USD, EUR, GBP and others; falls back to the latest previous quote on weekends and holidays | Banco Central do Brasil (Olinda OData) |

Example prompts once it is connected:

- "Which city is CEP 01310-100 in?"
- "How many business days are there between 2026-11-01 and 2026-12-31?"
- "Convert US$ 2,500 to BRL using today's PTAX selling rate."
- "Is 11.222.333/0001-81 a valid CNPJ? Who owns it?"

## Install

Requires Node.js 20+.

```bash
git clone <this repo>
cd mcp-brasil-data
npm install
npm run build
```

### Claude Code

```bash
claude mcp add brasil-data -- node /absolute/path/to/mcp-brasil-data/dist/index.js
```

### Claude Desktop

Add to `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "brasil-data": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-brasil-data/dist/index.js"]
    }
  }
}
```

## Development

| Command | What it does |
| --- | --- |
| `npm run build` | Compile TypeScript to `dist/` |
| `npm run typecheck` | Type-check without emitting |
| `npm test` | Unit + integration tests (Vitest) |

```
src/
  index.ts           stdio entry point
  server.ts          tool registration, input schemas, error mapping
  http.ts            fetch wrapper with timeout and typed errors
  validation.ts      CEP / CNPJ / date parsing and validation
  services/          one module per upstream API
test/
  server.test.ts     end-to-end through an in-memory MCP client
  services.test.ts   upstream mapping with a fake fetch
  validation.test.ts pure validation rules
```

## Design decisions

- **Dependency injection for I/O.** Every service receives a `fetch` function, and the server receives `fetch` and a clock. Tests never hit the network and the date defaults are deterministic.
- **End-to-end tests through the protocol.** `server.test.ts` connects a real MCP `Client` to the server over an in-memory transport and calls tools exactly like Claude would.
- **Errors are tool results, not crashes.** Validation and upstream failures come back as `isError: true` with a readable message, so the model can recover or explain the problem.
- **Validate before calling out.** Malformed CEPs and CNPJs with wrong check digits are rejected locally, saving a network round trip.
- **Dates are calendar dates.** All date math runs in UTC on `YYYY-MM-DD` values; "today" is resolved in the `America/Sao_Paulo` time zone.
- **Holidays follow BrasilAPI.** Its national list includes Carnival and Corpus Christi, which are optional days off for many employers. Business-day counts treat every listed date as a holiday, and the response says which ones were excluded.

## Limitations

- `lookup_cnpj` accepts numeric CNPJs only. The alphanumeric format validates offline, but public lookup APIs do not serve it yet.
- State and municipal holidays are not included.
- PTAX quotes are published on business days. Before the closing bulletin (around 1 p.m. Brasília time) the tool returns the latest intermediate bulletin and labels it.

## License

MIT