mcp-brasil-data

An MCP 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

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

Related MCP server: MCP Brazil Public Data

Install

Requires Node.js 20+.

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

Claude Code

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

Claude Desktop

Add to claude_desktop_config.json:

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

Development

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