内容
# CME 期货 MCP 服务器
[](https://github.com/aaronescribanogarcia-boop/cme-futures-mcp/actions/workflows/ci.yml)
[](https://www.python.org/)
[](LICENSE)
MCP 服务器，提供**标准化的 CME 期货数据**，可供任何 MCP 客户端（Claude Code、Cursor、Windsurf）使用。它提供后调整的连续日线、前月分钟线、合约规格和汇总统计数据，共有五个工具，并诚实地标注数据源（`adjusted` 为真或假），确保代理不会无声地混用调整和未调整的序列。
## 工具列表
| 工具 | 用途 |
|------|---------|
| `list_instruments()` | 符号、数据源、时间框架和日期范围。从这里开始。 |
| `get_ohlcv(symbol, timeframe='1d', start, end, n_bars)` | OHLCV 条形图。标注数据源和调整状态。行数限制（`truncated`/`n_total`）。 |
| `get_contract_specs(symbol)` | tick_size、point_value、tick_value、exchange、margin、RTH、currency。 |
| `get_summary_stats(symbol, timeframe='1d', start, end)` | 收益率、年化波动率（近似）、最大/最小值、最大回撤率——无需返回条形图。 |
`ping()` 是健康检查。
### 示例响应 (`get_ohlcv("NQ", "1d", n_bars=3)`)
```json
{
"symbol": "NQ",
"timeframe": "1d",
"source": "databento-badj",
"adjusted": true,
"schema_version": "1",
"n_returned": 3,
"n_total": 3,
"truncated": false,
"bars": [
{"t": "2026-06-17T00:00:00Z", "o": 22014.25, "h": 22180.50, "l": 21975.00, "c": 22156.75, "v": 412233},
{"t": "2026-06-18T00:00:00Z", "o": 22156.75, "h": 22240.00, "l": 22090.25, "c": 22118.50, "v": 388910},
{"t": "2026-06-19T00:00:00Z", "o": 22118.50, "h": 22305.75, "l": 22101.00, "c": 22287.25, "v": 401557}
]
}
```
价格按 tick 四舍五入；`bars` 使用紧凑的键（`t,o,h,l,c,v`）以在代理上下文中降低 token 使用量。
## 数据源（诚实标注）
- **`databento-badj`** — 后调整，连续，**仅限日线**。`adjusted=true`。
- **`yahoo-unadjusted`** — 前月拼接，**未调整**。`adjusted=false`。分钟线（1m/5m/15m/1h）和日线适用于微型合约。
对于后调整的符号，日线请求从 `databento-badj`（优先）获取。其他请求从 `yahoo-unadjusted` 获取。每个响应都标注了数据源和调整状态；序列永远不会混合。
## 安装
```bash
pip install -e . # 或：uvx cme-futures-mcp （发布后）
```
## 数据提供（自带数据集）
**数据不随此软件包捆绑。** 通过 `CME_FUTURES_DATA_DIR` 环境变量将服务器指向您自己的 Parquet 数据集：
```
$CME_FUTURES_DATA_DIR/
futures_daily_badj/<SYM>/1d.parquet # 后调整，连续，日线
futures/<SYM>/<tf>.parquet # 前月，分钟线
```
每个 Parquet 文件必须具有 UTC `DatetimeIndex` 和 `open, high, low, close, volume` 列。如果 `CME_FUTURES_DATA_DIR` 未设置，服务器将回退到软件包旁的 `data/` 目录。
## 运行
```bash
CME_FUTURES_DATA_DIR=/path/to/data python -m cme_futures_mcp.server
```
## 客户端注册
相同的服务器块适用于所有 MCP 客户端（它使用标准输入/输出）。
**Claude Code** — 在仓库根目录下的 `.mcp.json` 中：
```json
{
"mcpServers": {
"cme-futures": {
"command": "uvx",
"args": ["cme-futures-mcp"],
"env": { "CME_FUTURES_DATA_DIR": "/path/to/data" }
}
}
}
```
**Cursor** — `.cursor/mcp.json`（项目）或 `~/.cursor/mcp.json`（全局）：与上述相同的 `mcpServers` 块。
**Claude Desktop** — `claude_desktop_config.json`（设置 → 开发人员 → 编辑配置）：与上述相同的 `mcpServers` 块。
重启客户端并确认 `cme-futures` 显示为已连接（Claude Code 中的 `/mcp`）。
## 开发
```bash
pip install -e ".[dev]"
ruff check .
pytest -m "not slow" # 合成数据；无需真实数据集
```
MCP 逻辑在私有研究 monorepo 中维护（源代码），并使用 `python tools/sync_from_monorepo.py` 同步到此处。不要手动编辑同步模块（`server.py`、`data_access.py`、`serialization.py`、`contracts.py`、`storage.py`）；它们在每次发布时都会重新生成。
