mcp-cbr-rates

Un servidor del Protocolo de Contexto de Modelo (MCP) que expone datos públicos del Banco de Rusia (Центральный банк РФ, CBR) — cotizaciones de divisas, tasa clave, inflación y una instantánea macro compacta — a agentes de IA.

GitHub

Prueba este MCPPatrocinado

Documentación

mcp-cbr-rates

Un servidor de Model Context Protocol (MCP) que expone datos públicos del Banco de Rusia (Центральный банк РФ, CBR) — cotizaciones de divisas, tasa clave, inflación y una instantánea macro compacta — a agentes de IA.

mcp-cbr-rates forma parte de la familia atomno de servidores MCP centrados en el ecosistema fintech ruso. Es totalmente de código abierto, no requiere claves API y está construido sobre los endpoints públicos oficiales del CBR.

Características

Cinco herramientas MCP de alta calidad, cada una con un esquema Pydantic estricto: get_rate, history_rates, key_rate, inflation, statistics.
Caché TTL (Time-To-Live) integrada: 1 hora para cotizaciones diarias, 24 horas para series históricas, para ser respetuoso con la fuente.
Transporte asíncrono httpx con reintentos automáticos en errores 5xx.
Análisis XML seguro mediante defusedxml.
Más de 50 pruebas unitarias con HTTP simulado mediante respx, cobertura ≥80 %.
Sin secretos, sin telemetría, sin rastreadores de terceros.

Inicio rápido

Instalación desde PyPI (recomendada)

pipx install atomno-mcp-cbr-rates
atomno-mcp-cbr-rates  # starts the MCP server over stdio

O con uv:

uv tool install atomno-mcp-cbr-rates

Instalación desde el código fuente

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

Uso con Cursor

Añade lo siguiente a .cursor/mcp.json (o a tu ~/.cursor/mcp.json global):

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

Uso con Claude Desktop

Añade a claude_desktop_config.json:

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

En Windows la configuración se encuentra en %APPDATA%\Claude\claude_desktop_config.json; en macOS en ~/Library/Application Support/Claude/claude_desktop_config.json.

Uso con Claude Code

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

Herramientas

Nombre	Entradas	Devuelve
`get_rate`	`char_code: str`, `on_date?: date`	`CurrencyRate` — cotización única en la fecha dada (o la más reciente)
`history_rates`	`char_code: str`, `date_from: date`, `date_to: date`	`HistoryRates` — serie de cotizaciones diarias
`key_rate`	`date_from?: date`, `date_to?: date`	`KeyRateHistory` — serie de la tasa clave del CBR
`inflation`	`year_from?: int`, `year_to?: int`	`InflationData` — IPC mensual interanual en porcentaje
`statistics`	(ninguna)	`MacroSnapshot` — panel combinado: tasa clave + USD/EUR/CNY + inflación

Ejemplos en lenguaje natural:

"¿Cuál fue la tasa oficial del EUR el 25 de abril de 2024?" Herramienta: get_rate(char_code="EUR", on_date="2024-04-25")

"Traza la tasa diaria USD-RUB de los últimos 90 días." Herramienta: history_rates(char_code="USD", date_from=..., date_to=...)

"Dame la tasa clave más reciente, USD/EUR/CNY e inflación de una sola vez." Herramienta: statistics()

La ventana de history_rates está limitada a 366 días; para períodos más largos, llama a la herramienta repetidamente.

Configuración

Todos los ajustes son opcionales y se leen de variables de entorno:

Variable	Predeterminado	Descripción
`MCP_CBR_HTTP_TIMEOUT`	`15`	Tiempo de espera HTTP en segundos para las llamadas al CBR.
`MCP_CBR_CACHE_DAILY_TTL`	`3600`	TTL de caché para cotizaciones diarias (segundos).
`MCP_CBR_CACHE_HISTORY_TTL`	`86400`	TTL de caché para series históricas y respuestas SOAP.
`MCP_CBR_LOG_LEVEL`	`INFO`	Nivel de registro estándar de Python.

Los nombres heredados CBR_* todavía se aceptan por compatibilidad, pero las configuraciones nuevas deben usar MCP_CBR_*.

No hay claves API que configurar: todos los endpoints del CBR utilizados aquí son públicos.

Desarrollo

git clone https://github.com/atomno-mcp/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

Estructura:

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

Fuentes de datos

https://www.cbr.ru/scripts/XML_daily.asp — cotizaciones diarias de divisas.
https://www.cbr.ru/scripts/XML_dynamic.asp — series históricas de divisas.
https://www.cbr.ru/scripts/XML_valFull.asp — consulta de códigos de divisas.
https://www.cbr.ru/DailyInfoWebServ/DailyInfo.asmx — servicio SOAP para la tasa clave del CBR.
https://www.cbr.ru/hd_base/infl/ — tabla de inflación mensual interanual.

Todos los endpoints son de solo lectura y gratuitos.

Aviso legal

Este proyecto no está afiliado al Banco de Rusia de ninguna manera. Es un envoltorio no oficial, de buena fe, alrededor de datos disponibles públicamente. Úsalo bajo tu propio riesgo; los autores declinan cualquier responsabilidad sobre la actualidad, precisión o aplicabilidad de los datos entregados a través de este servidor.

Si los esquemas HTML o XML del CBR cambian, algunas herramientas pueden dejar de funcionar hasta que este paquete se actualice. Por favor, abre un issue si notas una regresión.

Licencia

MIT — consulta LICENSE.