brasilapi-mcp

Un servidor Model Context Protocol (MCP) de creación propia que expone la BrasilAPI pública como herramientas que un cliente LLM (Claude Desktop, Claude Code o cualquier host MCP) puede llamar: consultar un CEP, un CNPJ, bancos, precios de vehículos FIPE, festivos nacionales y códigos de área DDD.

README en portugués

Por qué existe esto

Consumir el servidor MCP de otra persona es fácil; quería demostrar que puedo construir uno: esquemas de herramientas, un cliente HTTP tipado y una frontera que mantiene todo comprobable. BrasilAPI encaja bien: no necesita clave de API y sirve datos públicos, así que cualquiera puede clonar esto y ejecutarlo de inmediato, y cada herramienta se ejercita en las pruebas sin tocar la red.

Related MCP server: MCP Brasil API

Herramientas

Instalación

pip install -e .

Las dependencias son solo mcp (el SDK oficial de Python, v2) y httpx.

Ejecutarlo

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

El servidor habla MCP sobre stdio — normalmente no lo ejecutas a mano; un cliente MCP lo lanza y se comunica con él. python -m brasilapi_mcp.server también funciona.

Integrarlo en un cliente

Claude Desktop — añádelo a claude_desktop_config.json:

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

Si brasilapi-mcp no está en tu PATH, apunta command al script de tu venv (p. ej. .../.venv/Scripts/brasilapi-mcp en Windows) o usa "command": "python", "args": ["-m", "brasilapi_mcp.server"].

Claude Code — un comando:

claude mcp add brasilapi -- brasilapi-mcp

Luego pregunta, en lenguaje natural: "¿cuál es la dirección del CEP 01001-000?" o "lista los festivos nacionales de 2026", y el modelo llamará a la herramienta correspondiente.

Diseño — por qué se prueba sin conexión

La red está detrás de una frontera inyectable. BrasilAPIClient acepta un httpx.Client/transporte opcional, por lo que el conjunto de pruebas pasa un httpx.MockTransport con JSON prefabricado y se ejecuta sin E/S de red real. Las implementaciones de las herramientas son envoltorios finos sobre funciones síncronas simples que reciben el cliente explícitamente, así que la lógica se puede probar unitariamente de forma aislada, y un BrasilAPIError se convierte en un mensaje limpio que el modelo puede leer en lugar de un traceback.

Pruebas

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

El conjunto de pruebas cubre el cliente (cada endpoint, normalización de entradas, manejo de 404/500) contra un transporte simulado, las funciones de lógica de las herramientas y el registro de herramientas del servidor. Nada toca la red.

Una nota sobre los datos

BrasilAPI es un servicio público y no necesita clave; este servidor no almacena secretos ni lee variables de entorno. Las respuestas reales pertenecen a BrasilAPI y a sus fuentes upstream.

Licencia

MIT — consulta LICENSE.