mcp-cbr-rates

mcp-cbr-rates

一个模型上下文协议（MCP）服务，向 AI Agent 提供俄罗斯银行 （Центральный банк РФ，CBR）的公开数据——货币报价、关键利率、通胀 和精简宏观概览。

mcp-cbr-rates 是 atomno 系列 MCP 服务的一员，专注于俄罗斯金融科技生态。它完全开源，无需 API 密钥，并基于 CBR 官方公开端点构建。

---

功能

• 五个高质量 MCP 工具，每个工具都有严格的 Pydantic 模式： get_rate、history_rates、key_rate、inflation、statistics。
• 内置 TTL（生存时间）缓存：每日报价缓存 1 小时，历史序列缓存 24 小时，以减少对数据源的请求。
• 异步 httpx 传输，并在发生 5xx 错误时自动重试。
• 使用 defusedxml 安全解析 XML。
• 50 多项单元测试，使用 respx 模拟 HTTP，覆盖率 ≥80 %。
• 不含机密信息、无遥测、无第三方跟踪器。

---

快速开始

从 PyPI 安装（推荐）

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

或使用 uv：

uv tool install atomno-mcp-cbr-rates

从源代码安装

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

与 Cursor 配合使用

将以下内容添加到 .cursor/mcp.json（或全局配置文件 ~/.cursor/mcp.json）：

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

与 Claude Desktop 配合使用

添加到 claude_desktop_config.json：

{
  "mcpServers": {
    "cbr-rates": {
      "command": "atomno-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 -- atomno-mcp-cbr-rates

---

工具

名称	输入	返回值
get_rate	char_code: str、on_date?: date	CurrencyRate — 指定日期（或最新日期）的单个报价
history_rates	char_code: str、date_from: date、date_to: date	HistoryRates — 每日报价序列
key_rate	date_from?: date、date_to?: date	KeyRateHistory — CBR 关键利率序列
inflation	year_from?: int、year_to?: int	InflationData — 月度同比 CPI 百分比
statistics	(无)	MacroSnapshot — 综合仪表盘：关键利率 + USD/EUR/CNY + 通胀

英文自然语言示例：

“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 天；要查询更长时间，请多次调用该工具。

---

配置

所有设置均为可选项，通过环境变量读取：

变量	默认值	描述
MCP_CBR_HTTP_TIMEOUT	15	CBR 调用的 HTTP 超时时间，单位为秒。
MCP_CBR_CACHE_DAILY_TTL	3600	每日报价的缓存 TTL（秒）。
MCP_CBR_CACHE_HISTORY_TTL	86400	历史序列和 SOAP 响应的缓存 TTL。
MCP_CBR_LOG_LEVEL	INFO	Python 标准日志级别。

为兼容性，仍接受旧版 CBR_* 名称，但新配置应使用 MCP_CBR_*。

无需配置 API 密钥——此处使用的所有 CBR 端点均为公开端点。

---

开发

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

目录结构：

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 架构发生变化，个别工具可能会停止工作，直到此软件包更新。如果您发现回归问题，请提交 issue。

---

许可证

MIT——请参阅 LICENSE。