内容
<!-- mcp-name: io.github.atomno-mcp/mcp-cbr-rates -->
# mcp-cbr-rates
> 一个Model Context Protocol（MCP）服务器，提供俄罗斯央行（Центральный банк РФ，**CBR**）的公开数据 —— 货币报价、关键利率、通货膨胀和紧凑的宏观快照 —— 给AI代理。
[](LICENSE)
[](https://pypi.org/project/atomno-mcp-cbr-rates/)
[](https://github.com/atomno-mcp/mcp-cbr-rates/releases)
[](tests/)
[](tests/)
[](https://glama.ai/mcp/servers/atomno-mcp/mcp-cbr-rates)
<a href="https://glama.ai/mcp/servers/atomno-mcp/mcp-cbr-rates">
<img width="380" height="200" src="https://glama.ai/mcp/servers/atomno-mcp/mcp-cbr-rates/badge" alt="mcp-cbr-rates MCP server" />
</a>
`mcp-cbr-rates` 是 [atomno](https://atomno-labs.ru) 家族的MCP服务器，专注于俄罗斯金融科技生态系统。它是完全开源的，不需要API密钥，是在官方公开的CBR端点上构建的。
---
## 功能特点
- 五个高质量的MCP工具，每个工具都有严格的Pydantic模式：`get_rate`、`history_rates`、`key_rate`、`inflation`、`statistics`。
- 内置TTL（Time-To-Live）缓存：每日报价为1小时，历史系列为24小时，以礼貌地对待数据源。
- 使用自动重试5xx错误的异步`httpx`传输。
- 通过`defusedxml`安全解析XML。
- 50多个单元测试，带有`respx`模拟的HTTP，覆盖率≥80%。
- 没有秘密，没有遥测，没有第三方跟踪器。
---
## 快速开始
### 从PyPI安装（推荐）
```bash
pipx install atomno-mcp-cbr-rates
atomno-mcp-cbr-rates # 在标准输入/输出上启动MCP服务器
```
或者使用`uv`:
```bash
uv tool install atomno-mcp-cbr-rates
```
### 从源码安装
```bash
git clone https://github.com/atomno-mcp/mcp-cbr-rates.git
cd mcp-cbr-rates
pip install -e .
atomno-mcp-cbr-rates # 在标准输入/输出上启动MCP服务器
```
### 与Cursor一起使用
将以下内容添加到`.cursor/mcp.json`（或您的全局`~/.cursor/mcp.json`）：
```json
{
"mcpServers": {
"cbr-rates": {
"command": "atomno-mcp-cbr-rates"
}
}
}
```
### 与Claude Desktop一起使用
添加到`claude_desktop_config.json`:
```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一起使用
```bash
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日的官方欧元汇率是多少？*"
> 工具：`get_rate(char_code="EUR", on_date="2024-04-25")`
> *"绘制过去90天的每日美元-卢布汇率。*"
> 工具：`history_rates(char_code="USD", date_from=..., date_to=...)`
> *"给我最新的关键利率、美元/欧元/人民币和通货膨胀率。*"
> 工具：`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端点都是公开的。
---
## 开发
```bash
git clone https://github.com/atomno-mcp/mcp-cbr-rates.git
cd mcp-cbr-rates
python -m venv .venv && source .venv/bin/activate # 或在Windows上使用 .\.venv\Scripts\activate
pip install -e ".[dev]"
pytest --cov=src/mcp_cbr_rates
```
布局：
```
apps/mcp-cbr-rates/
├── src/mcp_cbr_rates/
│ ├── server.py # FastMCP入口点，工具注册
│ ├── tools.py # 高级异步工具，带缓存
│ ├── client.py # httpx包装器，围绕CBR XML / SOAP / HTML端点
│ ├── schemas.py # Pydantic v2模型，用于输入和输出
│ ├── cache.py # 异步TTL缓存
│ ├── currency_codes.py # 静态ISO → CBR ID映射（带有动态回退）
│ └── errors.py # 类型异常层次结构
└── tests/ # respx模拟单元测试 + 夹具
```
---
## 数据源
* `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](LICENSE).
