mcp-cbr-rates

Сервер протокола контекста модели (MCP), предоставляющий ИИ-агентам публичные данные Банка России (ЦБ РФ) — котировки валют, ключевую ставку, инфляцию и краткую макроэкономическую сводку.

mcp-cbr-rates является частью семейства MCP-серверов atomno, ориентированных на российскую финтех-экосистему. Он полностью открыт, не требует API-ключей и построен на основе официальных публичных эндпоинтов ЦБ РФ.

Возможности

• Пять высококачественных инструментов MCP, каждый со строгой схемой Pydantic: get_rate, history_rates, key_rate, inflation, statistics.

• Встроенный кэш с TTL (Time-To-Live): 1 час для ежедневных котировок, 24 часа для исторических рядов, чтобы не перегружать источник.

• Асинхронный транспорт httpx с автоматическими повторными попытками при ошибках 5xx.

• Безопасный парсинг XML через defusedxml.

• 50+ модульных тестов с использованием respx для моков HTTP, покрытие ≥80%.

• Никаких секретов, никакой телеметрии, никаких сторонних трекеров.

Related MCP server: ozon-mcp

Быстрый старт

Установка из исходного кода

git clone https://github.com/atomno-labs/mcp-cbr-rates.git
cd mcp-cbr-rates
pip install -e .
mcp-cbr-rates  # starts the MCP server over stdio

Использование с Cursor

Добавьте следующее в .cursor/mcp.json (или в ваш глобальный ~/.cursor/mcp.json):

{
  "mcpServers": {
    "cbr-rates": {
      "command": "mcp-cbr-rates"
    }
  }
}

Использование с Claude Desktop

Добавьте в claude_desktop_config.json:

{
  "mcpServers": {
    "cbr-rates": {
      "command": "mcp-cbr-rates"
    }
  }
}

В Windows конфигурация находится по адресу %APPDATA%\Claude\claude_desktop_config.json; в macOS — ~/Library/Application Support/Claude/claude_desktop_config.json.

Использование с Claude Code

claude mcp add cbr-rates -- mcp-cbr-rates

Инструменты

Примеры на простом языке:

"Какой был официальный курс EUR на 25 апреля 2024 года?" Инструмент: get_rate(char_code="EUR", on_date="2024-04-25")

"Построй график ежедневного курса USD-RUB за последние 90 дней." Инструмент: history_rates(char_code="USD", date_from=..., date_to=...)

"Дай мне последнюю ключевую ставку, курсы USD/EUR/CNY и инфляцию за один раз." Инструмент: statistics()

Окно history_rates ограничено 366 днями; для более длительных периодов вызывайте инструмент повторно.

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

Все настройки являются необязательными и считываются из переменных окружения:

API-ключи настраивать не нужно — все используемые здесь эндпоинты ЦБ РФ являются публичными.

Разработка

git clone https://github.com/atomno-labs/mcp-cbr-rates.git
cd mcp-cbr-rates
python -m venv .venv && source .venv/bin/activate  # or .\.venv\Scripts\activate on Windows
pip install -e ".[dev]"
pytest --cov=src/mcp_cbr_rates

Структура:

apps/mcp-cbr-rates/
├── src/mcp_cbr_rates/
│   ├── server.py        # FastMCP entry point, tool registration
│   ├── tools.py         # high-level async tools with caching
│   ├── client.py        # httpx wrapper around CBR XML / SOAP / HTML endpoints
│   ├── schemas.py       # Pydantic v2 models for inputs & outputs
│   ├── cache.py         # async TTL cache
│   ├── currency_codes.py # static ISO → CBR id map (with dynamic fallback)
│   └── errors.py        # typed exception hierarchy
└── tests/               # respx-mocked unit tests + fixtures

Источники данных

• https://www.cbr.ru/scripts/XML_daily.asp — ежедневные котировки валют.

• https://www.cbr.ru/scripts/XML_dynamic.asp — исторические ряды валют.

• https://www.cbr.ru/scripts/XML_valFull.asp — справочник кодов валют.

• https://www.cbr.ru/DailyInfoWebServ/DailyInfo.asmx — SOAP-сервис для ключевой ставки ЦБ РФ.

• https://www.cbr.ru/hd_base/infl/ — таблица ежемесячной инфляции (год к году).

Все эндпоинты доступны только для чтения и предоставляются бесплатно.

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

Этот проект никак не связан с Банком России. Это неофициальная обертка над общедоступными данными, созданная «как есть». Используйте на свой страх и риск; авторы снимают с себя любую ответственность за актуальность, точность или применимость данных, предоставляемых через этот сервер.

Если HTML- или XML-схемы ЦБ РФ изменятся, отдельные инструменты могут перестать работать до обновления этого пакета. Пожалуйста, откройте issue, если заметите регрессию.

Лицензия

MIT — см. LICENSE.