mcp-cbr-rates

AI 에이전트에게 러시아 중앙은행(Центральный банк РФ, CBR)의 공개 데이터(환율, 기준 금리, 인플레이션 및 거시 경제 스냅샷)를 제공하는 MCP(Model Context Protocol) 서버입니다.

mcp-cbr-rates는 러시아 핀테크 생태계에 중점을 둔 atomno MCP 서버 제품군의 일부입니다. 완전한 오픈 소스이며, API 키가 필요 없고, 공식 CBR 공개 엔드포인트를 기반으로 구축되었습니다.

주요 기능

• 5개의 고품질 MCP 도구 (각 도구는 엄격한 Pydantic 스키마를 따름): get_rate, history_rates, key_rate, inflation, statistics.

• 내장 TTL(Time-To-Live) 캐시: 소스 서버에 대한 부하를 줄이기 위해 일일 시세는 1시간, 과거 데이터 시리즈는 24시간 동안 캐싱합니다.

• 5xx 오류 발생 시 자동 재시도를 지원하는 비동기 httpx 전송.

• defusedxml을 통한 안전한 XML 파싱.

• respx로 모의 HTTP 요청을 수행하는 50개 이상의 단위 테스트, 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

도구

일반 언어 예시:

"2024년 4월 25일 공식 EUR 환율은 얼마였나요?" 도구: get_rate(char_code="EUR", on_date="2024-04-25")

"지난 90일간의 일일 USD-RUB 환율을 그래프로 그려줘." 도구: history_rates(char_code="USD", date_from=..., date_to=...)

"최신 기준 금리, USD/EUR/CNY 환율, 인플레이션 데이터를 한 번에 알려줘." 도구: statistics()

history_rates의 조회 기간은 최대 366일로 제한됩니다. 더 긴 기간이 필요한 경우 도구를 여러 번 호출하세요.

설정

모든 설정은 선택 사항이며 환경 변수에서 읽어옵니다:

설정할 API 키는 없습니다. 여기서 사용되는 모든 CBR 엔드포인트는 공개되어 있습니다.

개발

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 — CBR 기준 금리를 위한 SOAP 서비스.

• https://www.cbr.ru/hd_base/infl/ — 월별 전년 대비 인플레이션 표.

모든 엔드포인트는 읽기 전용이며 무료입니다.

면책 조항

이 프로젝트는 러시아 중앙은행과 어떠한 방식으로도 관련이 없습니다. 이는 공개적으로 사용 가능한 데이터를 기반으로 한 비공식적인 최선의 노력으로 만들어진 래퍼입니다. 사용자의 책임하에 사용하시기 바라며, 저자는 이 서버를 통해 제공되는 데이터의 최신성, 정확성 또는 적용 가능성에 대해 어떠한 책임도 지지 않습니다.

CBR의 HTML 또는 XML 스키마가 변경될 경우, 이 패키지가 업데이트될 때까지 개별 도구가 작동하지 않을 수 있습니다. 회귀 문제가 발생하면 이슈를 제기해 주시기 바랍니다.

라이선스

MIT — LICENSE를 참조하세요.