mcp-cbr-rates

mcp-cbr-rates

Um servidor Model Context Protocol (MCP) que expõe dados públicos do Banco Central da Rússia (Центральный банк РФ, CBR) — cotações de moedas, taxa de juros básica, inflação e um resumo macroeconômico compacto — para agentes de IA.

mcp-cbr-rates faz parte da família atomno de servidores MCP focados no ecossistema fintech russo. É totalmente open-source, não requer chaves de API e é construído sobre os endpoints públicos oficiais do CBR.

---

Recursos

• Cinco ferramentas MCP de alta qualidade, cada uma com um esquema Pydantic estrito: get_rate, history_rates, key_rate, inflation, statistics.
• Cache TTL (Time-To-Live) integrado: 1 hora para cotações diárias, 24 horas para séries históricas, para ser educado com a fonte.
• Transporte assíncrono httpx com tentativas automáticas em erros 5xx.
• Parsing XML seguro via defusedxml.
• Mais de 50 testes unitários com HTTP simulado via respx, cobertura ≥80%.
• Sem segredos, sem telemetria, sem rastreadores de terceiros.

---

Início rápido

Instalar a partir do PyPI (recomendado)

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

Ou com uv:

uv tool install atomno-mcp-cbr-rates

Instalar a partir do código-fonte

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

Usar com Cursor

Adicione o seguinte ao .cursor/mcp.json (ou ao seu ~/.cursor/mcp.json global):

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

Usar com Claude Desktop

Adicione ao claude_desktop_config.json:

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

No Windows, a configuração fica em %APPDATA%\Claude\claude_desktop_config.json; no macOS, em ~/Library/Application Support/Claude/claude_desktop_config.json.

Usar com Claude Code

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

---

Ferramentas

Nome	Entradas	Retornos
get_rate	char_code: str, on_date?: date	CurrencyRate — cotação única na data informada (ou na mais recente)
history_rates	char_code: str, date_from: date, date_to: date	HistoryRates — série de cotações diárias
key_rate	date_from?: date, date_to?: date	KeyRateHistory — série da taxa de juros básica do CBR
inflation	year_from?: int, year_to?: int	InflationData — IPC mensal ano a ano em percentual
statistics	(nenhum)	MacroSnapshot — painel combinado: taxa básica + USD/EUR/CNY + inflação

Exemplos em linguagem simples:

"Qual era a cotação oficial do EUR em 25 de abril de 2024?" Ferramenta: get_rate(char_code="EUR", on_date="2024-04-25")

"Plote a taxa diária USD-RUB dos últimos 90 dias." Ferramenta: history_rates(char_code="USD", date_from=..., date_to=...)

"Me dê a taxa básica mais recente, USD/EUR/CNY e inflação de uma vez." Ferramenta: statistics()

A janela do history_rates é limitada a 366 dias; para períodos mais longos, chame a ferramenta repetidamente.

---

Configuração

Todas as configurações são opcionais e lidas de variáveis de ambiente:

Variável	Padrão	Descrição
MCP_CBR_HTTP_TIMEOUT	15	Timeout HTTP em segundos para chamadas ao CBR.
MCP_CBR_CACHE_DAILY_TTL	3600	TTL do cache para cotações diárias (segundos).
MCP_CBR_CACHE_HISTORY_TTL	86400	TTL do cache para séries históricas e respostas SOAP.
MCP_CBR_LOG_LEVEL	INFO	Nível de log padrão do Python.

Nomes legados CBR_* ainda são aceitos para compatibilidade, mas novas configurações devem usar MCP_CBR_*.

Não há chaves de API para configurar — todos os endpoints do CBR usados aqui são públicos.

---

Desenvolvimento

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

Estrutura:

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

---

Fontes de dados

• https://www.cbr.ru/scripts/XML_daily.asp — cotações diárias de moedas.
• https://www.cbr.ru/scripts/XML_dynamic.asp — séries históricas de moedas.
• https://www.cbr.ru/scripts/XML_valFull.asp — consulta de códigos de moedas.
• https://www.cbr.ru/DailyInfoWebServ/DailyInfo.asmx — serviço SOAP para a taxa básica do CBR.
• https://www.cbr.ru/hd_base/infl/ — tabela mensal de inflação ano a ano.

Todos os endpoints são somente leitura e gratuitos.

---

Aviso legal

Este projeto não é afiliado ao Banco Central da Rússia de forma alguma. É um wrapper não oficial, de melhor esforço, sobre dados publicamente disponíveis. Use por sua conta e risco; os autores se isentam de qualquer responsabilidade pela atualidade, precisão ou aplicabilidade dos dados entregues por este servidor.

Se os esquemas HTML ou XML do CBR mudarem, ferramentas individuais podem parar de funcionar até que este pacote seja atualizado. Por favor, abra uma issue se notar uma regressão.

---

Licença

MIT — veja LICENSE.