brasilapi-mcp

Ein eigenständig entwickelter Model Context Protocol (MCP)-Server, der die öffentliche BrasilAPI als Werkzeuge bereitstellt, die ein LLM-Client (Claude Desktop, Claude Code oder ein beliebiger MCP-Host) aufrufen kann: CEP, CNPJ, Banken, FIPE-Fahrzeugpreise, nationale Feiertage und DDD-Vorwahlen nachschlagen.

README em português

Warum es das gibt

Einen fremden MCP-Server zu nutzen ist einfach; ich wollte beweisen, dass ich einen bauen kann – Tool-Schemas, einen typisierten HTTP-Client und eine Grenze, die das Ganze testbar hält. BrasilAPI passt gut: Es benötigt keinen API-Schlüssel und liefert öffentliche Daten, sodass jeder dieses Repository klonen und sofort ausführen kann, und jedes Tool wird in Tests ohne Netzwerkzugriff geprüft.

Related MCP server: MCP Brasil API

Werkzeuge

Installation

pip install -e .

Die Abhängigkeiten sind nur mcp (das offizielle Python-SDK, v2) und httpx.

Ausführen

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

Der Server spricht MCP über stdio – normalerweise führt man ihn nicht von Hand aus; ein MCP-Client startet ihn und kommuniziert mit ihm. python -m brasilapi_mcp.server funktioniert ebenfalls.

In einen Client einbinden

Claude Desktop – fügen Sie zu claude_desktop_config.json hinzu:

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

Wenn brasilapi-mcp nicht in Ihrem PATH ist, setzen Sie command auf das Skript Ihrer venv (z. B. .../.venv/Scripts/brasilapi-mcp unter Windows) oder verwenden Sie "command": "python", "args": ["-m", "brasilapi_mcp.server"].

Claude Code – ein Befehl:

claude mcp add brasilapi -- brasilapi-mcp

Dann fragen Sie in einfacher Sprache: „Wie lautet die Adresse für CEP 01001-000?" oder „Liste die nationalen Feiertage 2026 auf", und das Modell ruft das passende Werkzeug auf.

Design – warum es offline getestet wird

Das Netzwerk befindet sich hinter einer injizierbaren Grenze. BrasilAPIClient akzeptiert einen optionalen httpx.Client/Transport, sodass die Testsuite einen httpx.MockTransport mit vorgefertigtem JSON übergibt und ohne echte Netzwerk-I/O läuft. Die Tool-Bodies sind dünne Wrapper um einfache, synchrone Funktionen, die den Client explizit übernehmen, sodass die Logik isoliert unit-testbar ist, und ein BrasilAPIError wird zu einer sauberen Meldung, die das Modell lesen kann, statt eines Tracebacks.

Testen

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

Die Suite deckt den Client (jeden Endpunkt, Eingabenormalisierung, 404/500-Behandlung) gegen einen Mock-Transport ab, die Tool-Logikfunktionen und die Tool-Registrierung des Servers. Nichts greift auf das Netzwerk zu.

Ein Hinweis zu den Daten

BrasilAPI ist ein öffentlicher Dienst und benötigt keinen Schlüssel; dieser Server speichert keine Geheimnisse und liest keine Umgebungsvariablen. Live-Antworten gehören BrasilAPI und seinen vorgelagerten Quellen.

Lizenz

MIT – siehe LICENSE.