brasilapi-mcp

Сервер собственной разработки на базе Model Context Protocol (MCP), который предоставляет публичный BrasilAPI в виде инструментов, доступных LLM-клиенту (Claude Desktop, Claude Code или любому MCP-хосту): поиск CEP, CNPJ, банков, цен на автомобили FIPE, национальных праздников и телефонных кодов DDD.

README на португальском

Зачем это существует

Пользоваться чужим MCP-сервером легко; я хотел доказать, что могу создать его сам — схемы инструментов, типизированный HTTP-клиент и границу, которая делает всё это тестируемым. BrasilAPI хорошо подходит: ему не нужен API-ключ, и он отдаёт публичные данные, так что любой может склонировать репозиторий и сразу запустить его, а каждый инструмент проверяется в тестах без обращения к сети.

Related MCP server: MCP Brasil API

Инструменты

Установка

pip install -e .

Зависимости — это только mcp (официальный Python SDK, v2) и httpx.

Запуск

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

Сервер общается по MCP через stdio — обычно его не запускают вручную; его запускает MCP-клиент и общается с ним. python -m brasilapi_mcp.server тоже работает.

Подключение к клиенту

Claude Desktop — добавьте в claude_desktop_config.json:

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

Если brasilapi-mcp нет в PATH, укажите в command путь к скрипту вашего venv (например, .../.venv/Scripts/brasilapi-mcp в Windows) или используйте "command": "python", "args": ["-m", "brasilapi_mcp.server"].

Claude Code — одна команда:

claude mcp add brasilapi -- brasilapi-mcp

Затем спросите обычным языком: «какой адрес у CEP 01001-000?» или «перечисли национальные праздники в 2026 году» — и модель вызовет нужный инструмент.

Устройство — почему тесты работают офлайн

Сеть находится за инжектируемой границей. BrasilAPIClient принимает необязательный httpx.Client/транспорт, поэтому тесты передают httpx.MockTransport с заранее подготовленными JSON-данными и работают без реального сетевого ввода-вывода. Тела инструментов — тонкие обёртки над обычными синхронными функциями, которые явно принимают клиент, так что логику можно юнит-тестировать изолированно, а BrasilAPIError превращается в понятное сообщение, которое модель может прочитать вместо traceback.

Тестирование

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

Тесты покрывают клиент (каждую конечную точку, нормализацию входных данных, обработку ошибок 404/500) с mock-транспортом, функции логики инструментов и регистрацию инструментов на сервере. Никаких обращений к сети.

Примечание о данных

BrasilAPI — это публичный сервис, и ему не нужен ключ; этот сервер не хранит секретов и не читает переменные окружения. Актуальные ответы принадлежат BrasilAPI и её вышестоящим источникам.

Лицензия

MIT — см. LICENSE.