Quant Research MCP

quant_research_mcp

一个 MCP 服务，提供有论文依据的量化交易方法注册表，以及确定性、无需大模型的决策助手。服务提供可复现的数学计算（筛选、指标、市场状态检测、方法信号、评分入场决策）；调用方 Agent 提供判断（例如，将新闻标题解读为情绪信号）。不使用 claude -p，不运行子进程，服务内部不使用大模型。

⚠️ 不构成金融建议。 这是只读的研究与教育工具。它只执行量化计算，不会下单。它输出的任何内容都不是投资建议或推荐。市场数据可能延迟或有误，回测不代表预测，交易存在重大亏损风险。您独自承担所冒风险的一切责任。 本软件按“原样”提供，不附带任何保证 — 请参阅 LICENSE。

项目缘由

将一个可用的日内交易流程重新打包为可组合的 MCP 工具，目标有两个：

1. 可扩展以支持未来的论文。 每种策略都是在注册表中注册的 TradingMethod。添加一篇新论文 = 新增一个模块，调用 register(...)，再导入它。其他内容无需更改。
2. 决策基于科学，而非生成。 旧流程通过大模型调用来筛选入场机会。此处改用 quant_score_decision — 一个纯函数，将回报风险比、市场状态强度、成交量、RSI 位置和经 ATR 归一化的止损质量组合为可审计的评分。输入相同 → 输出相同。

工具（13 个）

工具	网络	用途
quant_list_methods	否	列出已注册的方法（键、论文、时间范围、市场状态）。
quant_describe_method	否	查看某种方法的完整详情和引用。
quant_screen_universe	是	按跳空幅度 / 相对成交量 / ATR% 对股票代码排序。
quant_compute_indicators	是	计算某只股票的 EMA9/20、RSI、ATR、VWAP、Hurst。
quant_detect_regime	是	通过 Hurst 判断市场状态：TRENDING / MEAN_REVERTING / RANDOM_WALK。
quant_analyze_setup	是	对单只股票运行方法 → 生成信号 + 入场价/止损价/目标价（含 HTF 背景）。
quant_analyze_universe	是	运行全市场方法：动量排序、配对价差。
quant_backtest_method	是	验证方法：在历史数据上重放其自身的 analyze() → 胜率、期望收益、回撤、样本内/样本外两部分。
quant_check_events	是	下一次财报（+天数）、除息 — 二元事件风险。
quant_portfolio_risk	是	无状态地检查风险敞口 / 相关性 / 集中度 + 候选标的判定。
quant_market_context	是	SPY/QQQ/IWM、VIX、11 个行业板块排序、风险偏好广度。
quant_score_decision	否	决策助手：交易设置（+ 情绪、财报、风险敞口）→ 评分、判定、仓位规模、考虑时间范围的执行计划。结果具有确定性。
quant_fetch_news	是	获取近期新闻标题（仅提供数据；由 Agent 判断情绪）。

所有工具均为只读，并支持 response_format: markdown | json。

工作流

日内交易

quant_market_context                  # tape read: risk-on/off, sectors
  → quant_screen_universe             # find movers
  → quant_analyze_setup               # hurst_regime_orb on the top name
  → quant_check_events + quant_fetch_news   # binary risk + agent sentiment
  → quant_portfolio_risk              # heat/correlation vs your open book
  → quant_score_decision(setup, news_sentiment, days_to_earnings,
                         portfolio_heat_pct)

波段交易（数天） — 通过 quant_analyze_setup / quant_analyze_universe 使用 rsi2_reversion、pairs_cointegration；此处盈利报告否决最为重要 （quant_check_events → days_to_earnings）。

持仓交易（数周以上） — 对每个代码使用 donchian_trend，对整个 交易标的范围使用 xs_momentum；每月重新排序，每周根据执行计划审查止损。

信任任何方法之前：针对你的代码和时间段运行 quant_backtest_method — 它会结合成本重放该方法自身的信号逻辑，并报告样本内与样本外两部分的结果， 让你查看策略衰减情况。

Agent 负责撰写叙述内容；服务端保证数字准确。

决策辅助工具（quant_score_decision）

纯函数。综合评分（权重见 config.DECISION_WEIGHTS）：

• reward_risk — 已实现的风险回报比与目标倍数的对比。
• regime_strength — 缩放后的 |Hurst − 0.5|（与随机游走的距离）。
• volume_confirmation — 相对成交量与最低阈值的对比。
• momentum_position — RSI 是否处于符合方向的健康区间（而非已耗尽）。
• stop_quality — 按日 ATR 归一化的止损距离（过紧、容易受噪声影响的止损会被扣分）。

可选的 news_sentiment（由 Agent 推导）会提升方向一致的评分，或在置信度 ≥ 0.5 时否决方向相悖的评分。输出包含各因素的明细、固定比例的 position_size（对过紧、 容易受噪声影响的止损进行折减），以及按机械规则推导的 execution_plan（入场触发条件、订单类型、止损阶梯、 止盈、时间止损、取消条件）。

内置方法（5 种）

Key	时间周期	论文
hurst_regime_orb	日内	arXiv:2205.11122 — Hurst 市场状态 → ORB / VWAP 均值回归
rsi2_reversion	波段	Connors & Alvarez 2009 — 200 日 SMA 上方的 RSI(2) 回调
pairs_cointegration	波段	Gatev et al. 2006 — Engle-Granger 价差 z 分数
donchian_trend	持仓	Faith，Turtle Rules；Moskowitz et al. 2012 — 55 日突破，20 日/ATR 移动止损
xs_momentum	持仓	Jegadeesh & Titman 1993 — 12-1 横截面动量，前 N 名组合

数据提供方

默认使用 yfinance（免费，延迟约 15 分钟）。数据层通过提供方接口 （quant_research_mcp/providers/）接入：为 Alpaca/Polygon/IBKR 实现 DataProvider 协议，注册工厂，然后使用 QUANT_DATA_PROVIDER=<name> 运行。所有调用都会在进程内按 TTL 缓存（每日数据 15 分钟、日内数据 60 秒、新闻 5 分钟、事件/行业 1 小时）。

添加未来论文

# quant_research_mcp/methods/my_paper.py
from . import register
from .base import TradingMethod, TradeSetup

def analyze(daily, session, context) -> TradeSetup:
    ...  # compute signal, entry, stop, target

register(TradingMethod(
    key="my_paper_method",
    name="My Method",
    paper="Author et al., Title",
    paper_url="https://arxiv.org/abs/...",
    regime_applicability="TRENDING",
    description="One paragraph on the mechanics.",
    analyze=analyze,
))

然后在 methods/__init__.py 中添加 from . import my_paper。它现在会出现在 quant_list_methods 中，并可通过 quant_analyze_setup(method_key=...) 运行。

快速开始（Makefile）

make install      # create venv + install deps (uv sync)
make smoke        # import server, list the 13 tools (no network)
make run          # run the server over stdio
make help         # list every target

安装为 Shell 二进制文件

make install-cli              # installs `quant-research-mcp` onto your PATH (uv tool)
quant-research-mcp            # runs the server over stdio from anywhere

如果安装后找不到命令，请运行 uv tool update-shell 并重启 Shell（uv 的工具 bin 目录通常为 ~/.local/bin，必须位于 PATH 中）。

Target	功能
make install	uv sync — 创建 venv 并安装依赖
make install-cli	将 quant-research-mcp 二进制文件安装到 PATH
make uninstall-cli	移除二进制文件
make dev	安装并安装用于代码检查的 ruff
make run	运行 MCP 服务（stdio）
make smoke	导入并列出工具，不访问网络
make test	运行 pytest 测试套件（不访问网络）
make inspect	启动 MCP Inspector
make check	测试 + 代码检查 + 断言没有 LLM/子进程调用
make register	输出 stdio 客户端配置 JSON
make claude-add	将本地克隆注册到 Claude Code（用户范围）
make claude-remove	从 Claude Code 中移除
make build	将 sdist 和 wheel 构建到 dist/
make docker-build	在本地构建 Docker 镜像
make mcpb	打包 Claude Desktop .mcpb 包
make clean	清除缓存、venv 和构建产物

安装

每种方式运行的都是同一个 stdio 服务 — 选择适合你的方式。

方式	命令	需要
通过 GitHub 使用 uvx（无需克隆）	uvx --from git+https://github.com/FlawlessByte/quant-research-mcp quant-research-mcp	uv
PyPI	uvx quant-research-mcp · pipx install quant-research-mcp	uv / pipx
Docker	docker run -i --rm ghcr.io/flawlessbyte/quant-research-mcp	Docker
从源代码安装	git clone … && cd quant-research-mcp && make install	git + uv
Claude Desktop	从最新版本安装 .mcpb	Claude Desktop

PyPI 和 Docker 镜像会随带标签的版本发布；在首次发布之前， 请使用通过 GitHub 使用 uvx或从源代码安装的方式。

与 Claude Code 搭配使用

最快的方式 — 直接从 GitHub 运行，无需克隆：

claude mcp add quant_research -- \
  uvx --from git+https://github.com/FlawlessByte/quant-research-mcp quant-research-mcp

发布到 PyPI 后，可简化为：

claude mcp add quant_research -- uvx quant-research-mcp

容器化方式：

claude mcp add quant_research -- docker run -i --rm ghcr.io/flawlessbyte/quant-research-mcp

从本地克隆进行开发：make claude-add 会在用户级别注册此检出版本；make register 会输出可直接粘贴的 .mcp.json 代码块。

在 Claude Code 中验证：

/mcp                       # should list 'quant_research' as connected

然后提出类似 “筛选整个标的范围，并用 hurst 方法分析排名第一的标的，接着评估入场决策。” 的请求。它会依次调用 quant_screen_universe → quant_analyze_setup → quant_score_decision。

从源代码安装（开发）

git clone https://github.com/FlawlessByte/quant-research-mcp
cd quant-research-mcp
make install      # uv sync — venv + dependencies
make smoke        # list the 13 tools (no network)
make test         # 40 offline tests

可选：make install-cli 会通过 uv tool 将 quant-research-mcp 二进制文件添加到 PATH。如果之后找不到它，请运行 uv tool update-shell 并重启 shell。使用 make inspect 检查工具架构。

发布（维护者）

CI 会在每次推送/PR 时运行 ruff 和 40 项离线测试（Python 3.12 和 3.13）。 发布由标签驱动：

# bump version in pyproject.toml + server.json + manifest.json, commit, then:
git tag v0.1.0 && git push origin v0.1.0

这会触发两个工作流：

• release.yml → 运行 uv build，通过 Trusted Publishing（OIDC，无需存储令牌）发布到 PyPI，并将 wheel/sdist 和 .mcpb 捆绑包附加到 GitHub Release。
• docker.yml → 构建并推送 ghcr.io/flawlessbyte/quant-research-mcp。

一次性设置：

1. **PyPI：**创建项目并添加 Trusted Publisher（所有者 FlawlessByte、仓库 quant-research-mcp、工作流 release.yml、环境 pypi）。
2. **GHCR：**首次推送后，将软件包可见性设为公开。
3. **MCP registry：**首次发布到 PyPI 后，使用 mcp-publisher CLI 注册 — 运行 mcp-publisher login github，然后运行 mcp-publisher publish（使用 server.json；GitHub 登录可证明你拥有 io.github.FlawlessByte/… 命名空间）。

Claude Desktop 的 .mcpb 会在后台调用 uvx，因此一键安装仍要求设备上已安装 uv — 直接打包 pandas/scipy/statsmodels 的 wheel 会导致体积庞大且依赖特定平台。

局限性（严肃交易者仍需从其他渠道获取的内容）

• 数据有延迟，除非接入实时数据提供商密钥（接口已就绪；yfinance 数据约延迟 15 分钟，新闻源也较少）。
• 没有宏观日历（FOMC/CPI/NFP）— 没有可靠的免费数据源；请通过 news_sentiment / news_confidence 提供自己的判断。
• 没有期权数据（IV、期限结构、Gamma 水平），也没有卖空兴趣/流通股数和 Level 2 数据 — 这些是下一步的发展方向。
• 回测用于验证参数，而非预测：yfinance 历史数据存在幸存者偏差，成本只是估算值，提供商将 5 分钟 K 线的日内回放限制在约 60 天。
• 按设计不持久化数据 — 服务不存储任何内容；每次调用时都要提供未平仓头寸（quant_portfolio_risk）。交易日志是计划中的可选模块。