MCP Brasil — Сценарии использования, Установка & Живое демо

Name: MCP Brasil MCP Server
Author: Mcp-Brasil

Зачем использовать

Ключевые функции

70+ бразильских публичных API в одном месте
Не требует API-ключей для открытых данных
Цепочка резервных источников ViaCEP / BrasilAPI / OpenCEP — запросы CEP всегда отвечают
Поиск по CNPJ через Receita Federal с автоматической обработкой rate-лимитов
Ежедневные курсы BCB и временные ряды SELIC
Поддерживается бразильским сообществом разработчиков

Живое демо

Как выглядит на практике

mcp-brasil.replay ▶ готово

0/0

Установка

Выберите клиент

~/Library/Application Support/Claude/claude_desktop_config.json · Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "mcp-brasil": {
      "command": "uvx",
      "args": [
        "mcp-brasil"
      ]
    }
  }
}

Откройте Claude Desktop → Settings → Developer → Edit Config. Перезапустите после сохранения.

~/.cursor/mcp.json · .cursor/mcp.json

{
  "mcpServers": {
    "mcp-brasil": {
      "command": "uvx",
      "args": [
        "mcp-brasil"
      ]
    }
  }
}

Cursor использует ту же схему mcpServers, что и Claude Desktop. Конфиг проекта приоритетнее глобального.

VS Code → Cline → MCP Servers → Edit

{
  "mcpServers": {
    "mcp-brasil": {
      "command": "uvx",
      "args": [
        "mcp-brasil"
      ]
    }
  }
}

Щёлкните значок MCP Servers на боковой панели Cline, затем "Edit Configuration".

~/.codeium/windsurf/mcp_config.json

{
  "mcpServers": {
    "mcp-brasil": {
      "command": "uvx",
      "args": [
        "mcp-brasil"
      ]
    }
  }
}

Тот же формат, что и Claude Desktop. Перезапустите Windsurf для применения.

~/.continue/config.json

{
  "mcpServers": [
    {
      "name": "mcp-brasil",
      "command": "uvx",
      "args": [
        "mcp-brasil"
      ]
    }
  ]
}

Continue использует массив объектов серверов, а не map.

~/.config/zed/settings.json

{
  "context_servers": {
    "mcp-brasil": {
      "command": {
        "path": "uvx",
        "args": [
          "mcp-brasil"
        ]
      }
    }
  }
}

Добавьте в context_servers. Zed перезагружается автоматически.

claude mcp add mcp-brasil -- uvx mcp-brasil

Однострочная команда. Проверить: claude mcp list. Удалить: claude mcp remove.

Сценарии использования

Реальные сценарии: MCP Brasil

Как провести экспресс-проверку бразильского контрагента по CNPJ

👤 Бразильские B2B-продавцы, юристы, операции финтех ⏱ ~10 min intermediate

Когда использовать: Вы собираетесь подписать договор с поставщиком и хотите проверить юридический статус, партнёров и адрес из официальных источников.

Предварительные требования

CNPJ контрагента — 14-значный номер, с форматированием или без

Поток

Получить профиль по CNPJ

Use mcp-brasil. Look up CNPJ 33.000.167/0001-01 and tell me legal name, status (ATIVA?), CNAE, capital social, partners.✓ Скопировано

→ Структурированный профиль со всеми полями
Сверить адрес

Take the registered CEP. Resolve via ViaCEP. Does the city match what Receita reports?✓ Скопировано

→ Совпадение / несоответствие выделено
Проверка санкций

Check the partners' CPFs against any sanction lists this MCP exposes. Anything?✓ Скопировано

→ Список совпадений или «чисто»

Итог: Одностраничное DD-резюме о контрагенте из официальных источников за 2 минуты.

Подводные камни

Receita ограничивает частые запросы — Инструмент уже выполняет повторные попытки с задержкой; для пакетов более 20 — делайте паузы вручную

Сочетать с: filesystem

Пакетная проверка бразильских адресов (CEP) перед рассылкой

👤 Логистика, электронная коммерция, очистка CRM ⏱ ~15 min beginner

Когда использовать: У вас есть CSV с адресами и CEP клиентов, и вы хотите навести порядок перед печатью 5000 этикеток.

Предварительные требования

addresses.csv со столбцом CEP — Любой CSV; Claude автоматически определит нужный столбец

Поток

Валидация

Use mcp-brasil. For every CEP in /data/addresses.csv, fetch via ViaCEP. Append city, state, neighborhood. Flag CEPs that don't resolve.✓ Скопировано

→ validated.csv с новыми столбцами и столбцом пометок
Сверка

For mismatches between CRM city and ViaCEP city, suggest the corrected city.✓ Скопировано

→ Отчёт о расхождениях

Итог: Чистый список адресов с источниками по каждой строке.

Подводные камни

Некоторые CEP являются «genéricos» (для целого города) — ViaCEP возвращает их без района — это ожидаемое поведение, а не ошибка

Сочетать с: filesystem

Получение показателей IBGE для анализа данных по Бразилии

👤 Аналитики данных, работающие с бразильскими рынками ⏱ ~20 min intermediate

Когда использовать: Вам нужны данные о населении, ВВП на душу населения или ИЧР по муниципиям или штатам.

Поток

Перечислить показатели

List IBGE indicators available via mcp-brasil related to GDP per capita.✓ Скопировано

→ Каталог показателей
Получить данные по штатам

Fetch GDP per capita for all 27 estados, latest year. Output to /data/gdp.csv.✓ Скопировано

→ CSV из 27 строк
Добавить слой с валютой

Convert to USD using BCB's official rate as of the same year. Add column.✓ Скопировано

→ Добавлен столбец USD

Итог: Воспроизводимый набор данных по штатам из IBGE + BCB.

Подводные камни

ID показателей IBGE периодически меняются — Всегда начинайте с инструмента каталога; не хардкодьте ID

Сочетать с: filesystem

Комбинации

Сочетайте с другими MCP — эффект x10

mcp-brasil + filesystem

Пакетная валидация CSV-файлов с адресами или CNPJ

mcp-brasil + postgres

Обогащение таблицы Postgres публичными данными

Инструменты

Что предоставляет этот MCP

Инструмент	Входные данные	Когда вызывать	Стоимость
viacep	cep: str	Разрешить любой бразильский CEP	бесплатно
cnpj_lookup	cnpj: str	Проверить бразильскую компанию	бесплатно (ограничено Receita)
bcb_rate	currency: str, date?: str	Получить официальный курс конвертации BRL (например, для бухгалтерии)	бесплатно
ibge_indicator	indicator_id: str, geo_level: 'br'\|'uf'\|'municipio', year?: int	Получить официальную статистику	бесплатно
inpi_search	query: str, kind: 'patent'\|'trademark'	Проверка предшествующего уровня техники по товарному знаку / патенту	бесплатно

Стоимость и лимиты

Во что обходится

Квота API: По источникам: ViaCEP без ограничений, Receita ~3 запроса/мин, BCB без ограничений
Токенов на вызов: 100–500
Деньги: Бесплатно
Совет: Для задач с большим числом запросов к Receita кэшируйте ответы в локальный JSON на день

Безопасность

Права, секреты, радиус поражения

Хранение учётных данных: Отсутствует для API открытых данных

Исходящий трафик: Каждый вызов уходит в соответствующий официальный API (viacep.com.br, receita, bcb, ibge и др.)

При передаче CPF/CNPJ реальных людей обращайтесь с ними как с персональными данными (PII) — наравне с любыми идентификаторами

Устранение неполадок

Частые ошибки и исправления

Запрос CNPJ к Receita возвращает 429

Превышен rate-лимит. Инструмент делает одну повторную попытку; иначе подождите 60 секунд.

Проверить: Одиночный запрос после паузы проходит

ViaCEP возвращает erro: true

CEP не существует или имеет неверный формат — проверьте формат ddddd-ddd

Показатель IBGE не возвращает данные за год

Некоторые показатели публикуются раз в несколько лет; запросите каталог доступных периодов

Альтернативы

MCP Brasil в сравнении

Альтернатива	Когда использовать	Компромисс
BrasilAPI (прямой REST)	Вам нужен один эндпоинт без слоя MCP	BrasilAPI в одиночку — это один источник CEP/CNPJ; mcp-brasil агрегирует 70+
Receita Federal напрямую	Вам нужны самые авторитетные данные CNPJ и вы готовы работать с их captcha	Неудобный UX; mcp-brasil использует кэшированные зеркала открытых данных

Ещё

Ресурсы

📖 Читать официальный README на GitHub

🐙 Открытые задачи

🔍 Все 400+ MCP-серверов и Skills