mcp-nbb

MCP-сервер для National Bank of Belgium SDMX статистического API.

Предоставляет 221 поток данных NBB (194 BE2 + 27 IMF/SDDS) в виде 6 удобных для LLM инструментов и 3 просматриваемых ресурсов, с встроенным обогащённым каталогом, чтобы LLM мог обнаруживать, описывать и запрашивать потоки данных без лишних вызовов API.

• Источник: https://nsidisseminate-stat.nbb.be/rest (NSI Web Service v8)

• Транспорт: stdio (стандартный MCP)

• Python: 3.11+

• Платформы: Linux, macOS, Windows

• 221 поток данных, классифицированных по 14 категориям — см. DATAFLOWS_CATALOG.md

Установка

Из PyPI (рекомендуется)

# With uv (runs without installing globally)
uvx mcp-nbb

# Or install into a regular venv
pip install mcp-nbb

Из исходного кода

git clone https://github.com/lacausecrypto/mcp-nbb.git
cd mcp-nbb
pip install -e .

Пакет поставляется с полным обогащённым каталогом (~9 МБ в src/nbb_mcp/data/catalog/). Для обычного использования не требуется этап сборки.

Related MCP server: OECD MCP Server

Конфигурация Claude Desktop

Отредактируйте ~/Library/Application Support/Claude/claude_desktop_config.json на macOS, %APPDATA%\Claude\claude_desktop_config.json на Windows или эквивалентный файл на Linux.

Использование uvx (рекомендуется после публикации на PyPI)

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

Из локальной редактируемой установки

macOS / Linux:

{
  "mcpServers": {
    "nbb": {
      "command": "/Users/you/projects/mcp-nbb/.venv/bin/mcp-nbb"
    }
  }
}

Windows:

{
  "mcpServers": {
    "nbb": {
      "command": "C:\\Users\\you\\projects\\mcp-nbb\\.venv\\Scripts\\mcp-nbb.exe"
    }
  }
}

Перезапустите Claude Desktop — 6 инструментов nbb_* появятся на панели MCP.

Инструменты

Темы nbb_quick

Ресурсы

Примеры запросов в Claude

"Какой курс EUR/USD за последний месяц?" → nbb_quick("exchange_rate", currency="USD", frequency="D", last_n_observations=30)

"Сравните рост ВВП Бельгии с уровнем безработицы с 2020 года." → nbb_compare([{dataflow_id:"DF_QNA_DISS",label:"GDP"}, {dataflow_id:"DF_UNEMPLOY_RATE",label:"Unemployment"}], start_period="2020-Q1")

"Найдите потоки данных NBB о потребительском кредите." → nbb_search("consumer credit") → nbb_describe(...) → nbb_query(...).

Конфигурация (переменные окружения)

Все настройки имеют разумные значения по умолчанию; их можно переопределить через переменные окружения.

Путь к кэшу по умолчанию определяется как:

• Linux: ~/.cache/mcp-nbb/

• macOS: ~/Library/Caches/mcp-nbb/

• Windows: %LOCALAPPDATA%\mcp-nbb\Cache\

Обновление каталога

Встроенный снимок src/nbb_mcp/data/catalog/ пересоздаётся путём получения DSD + списков кодов для каждого из 221 потоков данных:

mcp-nbb-build-catalog --force

Параметры:

• --force — пересоздать все карточки, игнорируя существующие.

• --limit N — обработать только первые N потоков (отладка).

• --only BE2/DF_EXR,BE2/DF_HICP_2025 — пересоздать конкретные потоки.

• --concurrency 5 — параллельные запросы DSD.

Полное пересоздание занимает ~80 секунд при обращении к живому API. Размер каталога ограничен ~9 МБ за счёт усечения списков кодов до 200 кодов на измерение (в некоторых потоках IMF более 65 000 кодов).

Еженедельное действие GitHub Action (build-catalog.yml) пересоздаёт каталог и открывает PR при обнаружении расхождений.

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

«WAF вернул HTML-редирект»

API NBB находится за WAF, который возвращает HTML-редирект с кодом 200 для любого запроса без браузерного User-Agent и заголовка Origin: https://dataexplorer.nbb.be. Клиент по умолчанию добавляет оба. Если вы переопределяете NBB_USER_AGENT, сохраняйте правдоподобную строку браузера.

«HTTP 404 NoResultsFound» при запросе данных

Ключ SDMX не соответствует ни одному ряду. Используйте nbb_describe(dataflow_id), чтобы увидеть допустимые коды, или передайте filters={} / key="all", чтобы получить все данные, а затем сузьте выборку с помощью start_period/end_period.

«Слишком много наблюдений, усечено»

Каждый ответ данных по умолчанию ограничен max_observations=200. Увеличьте через nbb_query(max_observations=1000) или сузьте запрос с помощью окна периода.

Каталог не найден

Если вы запускаете без встроенного src/nbb_mcp/data/catalog/, выполните mcp-nbb-build-catalog один раз, чтобы заполнить его.

Разработка

Полный рабочий процесс разработки см. в CONTRIBUTING.md. Краткая форма:

pip install -e ".[dev]"
pytest                     # full suite (unit + integration + E2E)
pytest -m "not e2e"        # fast subset
ruff check src tests
mcp-nbb-build-catalog      # refresh the bundled catalogue
mcp-nbb                    # run the server (stdio)

CI запускается на Linux, macOS и Windows с Python 3.11 и 3.12. Классифицированный перечень см. в DATAFLOWS_CATALOG.md.

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

Пожалуйста, сообщайте об уязвимостях конфиденциально — см. SECURITY.md.

Лицензия

MIT — полный текст см. в LICENSE.

Отказ от ответственности

Этот проект не связан с National Bank of Belgium и не одобрен им. Это независимый клиент их публичного SDMX REST API. Браузерные заголовки User-Agent и Origin требуются вышестоящим WAF и используются исключительно для доступа к публичным статистическим данным. Пользователи несут ответственность за соблюдение условий использования NBB.