内容
# 📈 量化研究助手 — MCP 服务器 & Claude 插件
> 一个一体化量化金融工具包，为 Claude 提供实时金融推理能力 —
> 价格与风险分析、策略回测、**隐马尔可夫模型市场状态检测**、期权希腊字母、基本面与贴现现金流估值、新闻情感分析、**基于状态的蒙特卡罗模拟**、
> 配对交易、Fama-French 因子归因、投资组合优化，以及一个综合的**量化评分**。所有数据源均为免费 — 无需 API 密钥。
由 **Rohan Inamdar** 构建 · [imrohaninamdar.com](https://imrohaninamdar.com) · [GitHub](https://github.com/irohan0)
---
## 与其他工具的区别
大多数量化工具提供一个笔记本或仪表板。而本工具为 Claude 提供**实时金融推理**：您可以与它用普通语言交流，它会在后台调用生产级别的金融工具，返回图表和结构化数据，并解释结果。
两个突出的非库功能：
- **隐马尔可夫模型市场状态检测** — 一个无监督的高斯隐马尔可夫模型，基于收益、已实现波动率、动量和 Z 分数特征训练，可以实时分类市场状态（牛市 / 熊市 / 高波动 / 横盘）。
- **基于状态的蒙特卡罗模拟** — 一个前向价格模拟，根据隐马尔可夫模型的转移矩阵在平静和紧张状态之间切换，因此下行尾部看起来更像真实市场，而不是一个整洁的钟形曲线。
---
## 工具（20 个）
### 分析
| 工具 | 功能 |
|------|-------------|
| `price_history` | 获取 OHLCV 数据，并附带蜡烛图 + 布林带 + 交易量图表 |
| `risk_metrics` | 夏普比率、索提诺比率、卡尔玛比率、VaR、CVaR、贝塔、詹森阿尔法、偏度、峰度 |
| `backtest` | 向量化的 SMA / RSI / 动量 / MACD 与买入并持有策略的回测 |
| `market_regime` | **高斯隐马尔可夫模型** 市场状态分类 + 转移矩阵 + 后验概率 |
| `portfolio_optimisation` | 最大夏普比率、最小波动率、风险平价 + 有效前沿 + 相关性热图 |
| `macro_overlay` | FRED 宏观指标（利率、CPI 环比、VIX、收益率曲线）+ 滚动相关性 |
| `options_analytics` | 隐含波动率偏度、看涨/看跌比率、最大痛苦、IV 期限结构、内部 **Black-Scholes 希腊字母** |
| `fundamentals` | 比率 + **两阶段贴现现金流 / 反向贴现现金流** + ** Piotroski F-Score** + **Altman Z-Score** |
| `sentiment` | 多源新闻标题情感分析（VADER 覆盖 yfinance + Yahoo/Google RSS） |
| `monte_carlo` | **基于状态的** / GBM / 自举法前向模拟，扇形图表，命中概率，预期 VaR |
| `technicals` | RSI、MACD、布林带、ADX、随机指标、ATR、OBV、支撑/阻力，模式 → 综合信号 |
| `pairs` | Engle-Granger + ADF 协整，套期比率，半衰期，Z 分数回测 |
| `factors` | **Fama-French 三因子 + 动量** 回归（贝塔，阿尔法，R²，贡献） |
| `composite_score` | **一个 0–100 的评分 + 强买入→强卖出** 判决，融合所有视角 |
### 持久状态
`add_to_watchlist` · `remove_from_watchlist` · `show_watchlist` · `save_portfolio_tool` · `load_portfolio_tool` · `list_portfolios_tool`
### 斜杠命令
`/quant-deep-dive <TICKER>` — 将工具链成一个有旁白的深度研究报告。
---
## 架构
```
Claude (MCP 客户端)
│ MCP 协议
▼
┌──────────────────────────────────────────────────────────┐
│ MCP 服务器 (Python / FastMCP) — 20 个工具 │
│ 价格 · 指标 · 回测 · 市场状态 · 投资组合 · 宏观经济 │
│ 期权 · 基本面 · 情感分析 · 蒙特卡罗模拟 │
│ 技术分析 · 配对交易 · 因子分析 · 评分 · 观察列表 │
│ 共享计算：pandas · numpy · scipy · hmmlearn · │
│ scikit-learn · statsmodels │
└──────────────────────────────────────────────────────────┘
│
▼ 数据源（全部免费，无密钥）
┌────────┐ ┌──────────┐ ┌────────────────┐ ┌───────────────┐ ┌────────────┐
│yfinance│ │ FRED CSV │ │ Ken French 库 │ │ Yahoo/Google │ │SQLite 缓存│
│（价格，│ │ （宏观经济）│ │ （Fama-French 因子）│ │ RSS（新闻） │ │+观察列表 │
│期权，│ └──────────┘ └────────────────┘ └───────────────┘ └────────────┘
│基本面）│
└────────┘
```
---
## 快速入门
### 1. 安装
```bash
git clone https://github.com/irohan0/quant-mcp.git
cd quant-mcp
python -m venv .venv && . .venv/bin/activate # Windows: .venv\Scripts\activate
pip install -r requirements.txt
```
### 2. 运行 MCP 服务器
```bash
python server.py
```
### 3a. 作为 Claude 代码插件使用（推荐：克隆 + 本地市场）
工具运行一个**本地 Python 进程**，因此机器需要依赖项。可靠的安装方法是克隆，构建 `.venv`（上述步骤 1），然后将本地检出添加为市场：
```
/plugin marketplace add /path/to/quant-mcp # CLAUDE_PLUGIN_ROOT → 您的检出（有 .venv)
/plugin install quant-research-assistant
```
20 个工具和 `/quant-deep-dive` 命令随后出现在您的会话中。验证 `claude mcp list` → 查找 `plugin:quant-research-assistant … √ 已连接`。
> **为什么是本地（不是裸 GitHub 市场安装）：** 插件的 MCP 配置
> ([mcp-config.json](mcp-config.json)) 启动 `${CLAUDE_PLUGIN_ROOT}/.venv/Scripts/python.exe`。
> 本地路径安装将 `CLAUDE_PLUGIN_ROOT` 指向您的检出位置，其中包含 `.venv`。纯粹的 `marketplace add <github-url>` 克隆存储库 *不带* （git-ignored） `.venv`，因此服务器没有解释器。如果您从 GitHub 安装，请在插件的缓存目录中创建 `.venv` + `pip install`，或编辑其 `mcp-config.json` 以指向具有依赖项的 Python。
> **在 macOS/Linux 上** 将路径更改为 `${CLAUDE_PLUGIN_ROOT}/.venv/bin/python`。
### 3b. 与 Claude 桌面版一起使用
将以下内容添加到 `claude_desktop_config.json`：
```json
{
"mcpServers": {
"quant-research-assistant": {
"command": "/path/to/quant-mcp/.venv/bin/python",
"args": ["/path/to/quant-mcp/server.py"]
}
}
}
```
### 4. （可选）用于演示的 Gradio 网页界面
```bash
python web/app.py # http://localhost:7860 — 每个工具一个标签页
```
---
## 示例提示
```
"给我 NVDA 的量化评分，并解释其分解"
"/quant-deep-dive AAPL"
"对 TSLA 进行基于状态的蒙特卡罗模拟，预测下一个季度 — 它达到 400 美元的概率是多少，预期下行风险是多少？"
"显示 AAPL 的期权：IV 偏度，看涨/看跌定位，最大痛苦和 ATM 希腊字母"
"KO-PEP 是否协整，以及配对回测的结果如何？"
"SPY 的 Fama-French 因子暴露和 3 年期的阿尔法是多少？"
"使用 AAPL、MSFT、GOOGL、SPY、BND、GLD 构建一个最大夏普比率的投资组合，并将其保存为 'core'"
```
---
## 运行测试
```bash
pytest tests/ -v # 51 个单元测试，完全无网络依赖（合成数据 + 模拟）
```
---
## 技术栈
- **MCP**: `mcp[cli]` （FastMCP）
- **数据（全部免费）**: `yfinance` （价格、期权、基本面），FRED CSV，Ken French 数据库，Yahoo/Google Finance RSS
- **计算**: `pandas`，`numpy`，`scipy`，`statsmodels`
- **机器学习**: `hmmlearn` （高斯隐马尔可夫模型），`scikit-learn`
- **情感分析**: `vaderSentiment`，`feedparser`
- **图表**: `matplotlib` （暗色主题，base64 PNG）
- **网页界面**: `gradio`
- **缓存和状态**: `sqlite3` （价格缓存 + 观察列表/投资组合）
---
## 项目结构
```
quant-mcp/
├── server.py ← MCP 服务器（注册所有 20 个工具）
├── mcp-config.json ← MCP 服务器配置（由插件引用）
├── .claude-plugin/
│ ├── plugin.json ← Claude 代码插件清单
│ └── marketplace.json ← 单插件市场
├── commands/
│ └── quant-deep-dive.md ← /quant-deep-dive 斜杠命令
├── tools/
│ ├── utils.py ← 缓存、获取、FRED、图表助手
│ ├── prices.py metrics.py backtest.py regime.py portfolio.py macro.py
│ ├── options.py fundamentals.py sentiment.py montecarlo.py
│ ├── technicals.py pairs.py factors.py score.py watchlist.py
├── web/app.py ← Gradio 网页界面（每个工具一个标签页）
├── tests/test_tools.py ← 51 个无网络依赖的单元测试
└── pyproject.toml
```
---
## 注意
- 所有数据源均为免费 — 无需 API 密钥。
- 图表为 base64 编码的 PNG，位于 `chart_png_b64` 字段 — 为用户渲染它们。
- SQLite 缓存避免冗余获取（价格 12 小时 TTL，基本面/因子 24 小时 TTL）。
- yfinance 和 RSS 为爬虫；当数据源不可用时，工具会优雅地降级。
- **仅用于教育 — 过去的业绩不能保证未来的结果。**
## 许可证
MIT © Rohan Inamdar
