# qlib-mcp

> **全网首个** Microsoft Qlib 量化研究平台的 MCP Server — 让 AI Agent 直接调用 Qlib 做数据查询、因子分析和策略回测。

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Python](https://img.shields.io/badge/python-3.10%2B-blue)](https://www.python.org/)
[![MCP](https://img.shields.io/badge/MCP-1.26%2B-green)](https://modelcontextprotocol.io/)
[![Qlib](https://img.shields.io/badge/Qlib-0.9%2B-orange)](https://github.com/microsoft/qlib)

---

## 功能概览

| 工具 | 说明 |
|------|------|
| `qlib_init` | 初始化 Qlib 数据环境（必须首先调用） |
| `qlib_download_data` | 获取 A 股/美股数据集下载命令 |
| `qlib_list_instruments` | 查询 CSI300/CSI500 等指数成分股列表 |
| `qlib_get_data` | 查询历史价格与因子数据（支持 Qlib 表达式） |
| `qlib_backtest_topk` | TopK 动量策略回测，返回年化收益/夏普/最大回撤 |
| `qlib_factor_analysis` | IC 分析 + 分位数收益，快速验证因子有效性 |
| `qlib_expression_help` | 表达式语法帮助（算子列��� / Alpha158 说明) |

---

## 安装

### 前置依赖

```bash
# Python 3.10+（推荐 3.12）
pip install pyqlib mcp
```

### 下载 Qlib 数据（A 股日线，约 500MB）

```bash
python -m qlib.run.get_data qlib_data \
  --target_dir ~/.qlib/qlib_data/cn_data \
  --region cn
```

### 注册到 MCP 客户端

**Claude Desktop / mcporter / Cursor:**

```json
{
  "mcpServers": {
    "qlib": {
      "command": "python",
      "args": ["/path/to/qlib-mcp/server.py"],
      "description": "Microsoft Qlib 量化研究平台"
    }
  }
}
```

> 请将 `python` 替换为你实际的 Python 路径（如 `/Users/你/.pyenv/versions/3.12.12/bin/python`）

---

## 使用示例

### 1. 初始化

```
调用 qlib_init，data_path = "~/.qlib/qlib_data/cn_data"，region = "cn"
```

### 2. 查询 CSI300 成分股

```
调用 qlib_list_instruments，market = "csi300"，start_date = "2024-01-01"
```

### 3. 获取平安银行近 60 日收盘价

```
调用 qlib_get_data，symbols = "SZ000001"，fields = "$close,$volume"，start_date = "2024-10-01"
```

### 4. 20 日动量因子 IC 分析

```
调用 qlib_factor_analysis，factor_expr = "$close / Ref($close, 20) - 1"
```

### 5. TopK 策略回测（CSI300，2020-2023）

```
调用 qlib_backtest_topk，market = "csi300"，topk = 50，signal_field = "$close / Ref($close, 20) - 1"
```

---

## Qlib 表达式语法速查

```
# 价格动量
$close / Ref($close, 20) - 1      # 20 日动量

# 技术指标
EMA($close, 12) - EMA($close, 26) # MACD
($close - Mean($close, 20)) / Std($close, 20)  # 布林带位置

# 成交量因子
$volume / Mean($volume, 20)        # 相对成交量
Corr($close, $volume, 10)          # 价量相关性（聪明钱）
```

完整算子列表：调用 `qlib_expression_help(topic="operators")`

---

## 受支持的市场

| 区域 | 常用成分股池 |
|------|------------|
| A 股（cn） | all, csi300, csi500, csi100, sz50 |
| 美股（us） | sp500, nasdaq100 |

---

## 许可证

MIT License

---

## 相关链接

- [Microsoft Qlib 官方仓库](https://github.com/microsoft/qlib)
- [Model Context Protocol](https://modelcontextprotocol.io/)
- [Qlib 文档](https://qlib.readthedocs.io/)