brasilapi-mcp

An authored Model Context Protocol (MCP) server that exposes the public BrasilAPI as tools an LLM client (Claude Desktop, Claude Code, or any MCP host) can call: look up a CEP, a CNPJ, banks, FIPE vehicle prices, national holidays, and DDD area codes.

README em português

Why this exists

Consuming someone else's MCP server is easy; I wanted to prove I can build one — tool schemas, a typed HTTP client, and a boundary that keeps the whole thing testable. BrasilAPI is a good fit: 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.

Related MCP server: MCP Brasil API

Tools

Install

pip install -e .

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

Run it

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 — 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 to claude_desktop_config.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:

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, so the logic is unit-testable in isolation, and a BrasilAPIError becomes a clean message the model can read instead of a traceback.

Testing

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

The suite covers the client (every endpoint, input normalization, 404/500 handling) against a mock transport, 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.