mt-data-mcp/README_CN.md

mtdata —— 把 MetaTrader 5 变成你的量化研究实验室

mtdata 是一个面向 Windows 的金融研究工具包，架设在 MetaTrader 5 之上，让你可以：

• 用命令行编写脚本、探索数据
• 让 AI 助手（Claude、Cursor、Trae 等）直接调用工具
• 在浏览器里打开图表工作台

它提供了 82 个工具，覆盖数据获取、预测、市场状态检测、形态识别、风险分析、交易执行，通过三层统一接口暴露出来。

⚠️ mtdata 是一个研究探索工具，不是交易策略，不构成投资建议。

---

核心理念

                    ┌─────────────────┐
                    │  MetaTrader 5   │
                    │   （Windows）    │
                    └────────┬────────┘
                             │
                      ┌──────▼──────┐
                      │   mtdata    │
                      │  （Python）  │
                      └──────┬──────┘
           ┌─────────────────┼─────────────────┐
           ▼                 ▼                 ▼
      mtdata-cli          MCP 服务器         Web API
     （命令行脚本）      （AI 助手调用）    （浏览器图表台）

三种入口，同一套工具，同一个后端。

---

适用人群

角色	你能做什么
学习型交易者	跟着引导流程学，从拉 K 线、做预测到跑回测，无需量化背景
系统化/量化交易者	原型策略、回测验证、优化止损止盈、通过 CLI 或 MCP 自动化
开发者/数据工程师	把 MT5 数据导入 Python 管线、AI Agent、本地 Web 应用

---

平台要求

要求	说明
操作系统	Windows（MT5 必须运行在 Windows 上）
Python	3.14（唯一支持的版本）
MetaTrader 5	安装并运行，强烈建议使用模拟账户
编译工具（可选）	Visual Studio Build Tools 2022 + "Desktop development with C++"（部分包需源码编译）

---

安全第一

trade_* 系列工具可以真实下单、修改、平仓。

• 始终使用模拟账户，直到你完全信任这个工具和你的经纪商行为
• 交易命令默认 --dry-run true（预览模式），确认后再设 --dry-run false
• 开启交易护栏：MTDATA_TRADE_GUARDRAILS_ENABLED=1
• 只做研究的话，只用 data_*、forecast_*、regime_*、patterns_*、report_*

---

功能全景

数据获取（3 个工具）

工具	说明
data_fetch_candles	拉取历史 K 线，可附带技术指标和去噪
data_fetch_ticks	拉取 Tick 数据
wait_event	阻塞等待时间边界或截止时间

品种管理（3 个工具）

工具	说明
symbols_describe	查询品种详细信息
symbols_list	列出品种或品种组
symbols_top_markets	按点差/成交量/价格变化排名

市场数据（8 个工具）

工具	说明
market_snapshot	统一交易前快照，多维度分析
market_status	交易所日历状态 / 品种可交易性
market_ticker	轻量报价快照（bid/ask/点差）
market_scan	市场扫描器，支持技术过滤
market_radar	小范围观察列表报价变化
market_microstructure_analyze	Tick 流动性分析
market_relative_strength	多品种相对强弱排名
market_depth_fetch ⚠️	需开启：Level 2 市场深度

预测（12 个工具）

工具	说明
forecast_generate	生成未来 N 根 K 线预测
forecast_list_methods	列出 71 种预测方法及可用状态
forecast_list_library_models	列出已注册模型
forecast_backtest_run	滚动窗口回测
forecast_barrier_prob	TP/SL 命中概率（蒙特卡洛/封闭解）
forecast_barrier_optimize	优化 TP/SL 障碍位
forecast_conformal_intervals	经验残差分位数预测区间
forecast_models_cleanup	清理过期模型
forecast_train	异步训练预测模型
forecast_task_cancel	取消异步任务
forecast_task_status	查询异步任务状态
forecast_task_list	列出所有异步任务

波动率 & 诊断（4 个工具）

工具	说明
volatility_term_structure	多周期已实现波动率锥
outliers_detect	异常 K 线检测
seasonality_detect	季节性周期检测
stationarity_test	平稳性检验（ADF/KPSS/PP）

因果分析（4 个工具）

工具	说明
correlation_matrix	多品种相关系数矩阵
cointegration_test	协整检验（EG/Johansen）
cross_correlation	两品种交叉相关/领先滞后
causal_discover_signals	Granger 因果发现

形态 & 状态（2 个工具）

工具	说明
patterns_detect	K 线/经典/谐波/艾略特波浪形态检测
regime_detect	市场状态检测（BOCPD/HMM/MS-AR/PELT/小波）

价位分析（4 个工具）

工具	说明
pivot_compute_points	枢轴点计算
support_resistance_levels	支撑阻力位检测
confluence_levels	多重共振区域
volume_profile_levels	成交量分布（POC/VAH/VAL）

技术方法（2 个工具）

工具	说明
denoise_describe	描述去噪方法及参数
denoise_list_methods	列出所有去噪方法

标签 & 时段（2 个工具）

工具	说明
labels_triple_barrier	Triple Barrier 标签
temporal_analyze	按星期/小时/交易时段分析

新闻 & 日历（2 个工具）

工具	说明
news	新闻聚合
calendar	经济日历

研究（3 个工具）

工具	说明
screener	股票筛选器
equity_profile	美股发行人档案
asset_performance	跨资产表现

期权（5 个工具）

工具	说明
options_chain	期权链快照
options_expirations	到期日列表
options_barrier_price	QuantLib 障碍期权定价
options_heston_calibrate	Heston 模型校准
options_provider_status	期权数据源状态

报告（1 个工具）

工具	说明
report_generate	生成研究风格报告

交易（17 个工具）

工具	说明
trade_place	下单（市价/挂单）
trade_modify	修改订单/持仓
trade_close	平仓/取消挂单
trade_get_open	查询持仓
trade_get_pending	查询挂单
trade_history	交易历史
trade_account_info	账户信息
trade_risk_analyze	风险敞口 + 仓位计算
trade_var_cvar_calculate	VaR/CVaR 估算
trade_stress_test	压力测试
trade_idea_compose	交易想法预览
trade_journal_analyze	交易日志分析
trade_execution_quality	成交质量分析
trade_session_context	交易会话上下文总览
portfolio_risk_decompose	组合风险分解
strategy_backtest	指标驱动策略回测
strategy_validate	策略样本外验证

---

技术指标（193 个）

所有指标来自 pandas-ta-classic，可通过 --indicators 参数在拉取 K 线时附加计算。完整列表见 指标列表.md。

分类	数量	代表指标
动量 (momentum)	53	RSI, MACD, Stoch, CCI, AO, Williams %R, TSI, TRIX, KDJ, Squeeze
覆盖 (overlap)	46	EMA, SMA, VWAP, Ichimoku, KAMA, HMA, SuperTrend, T3, ZLEMA, WMA
趋势 (trend)	26	ADX, Aroon, PSAR, Choppiness, Vortex, QStick, Decycler
成交量 (volume)	20	OBV, MFI, CMF, EOM, VFI, KVO, NVI, PVI
波动率 (volatility)	18	ATR, Bollinger Bands, Keltner, Donchian, Mass Index, Ulcer Index
统计 (statistics)	14	Beta, Kurtosis, Skew, Z-Score, Variance, Entropy
周期 (cycles)	8	EBSW, Hilbert Transform 系列, MSW
K线形态 (candles)	5	Doji, Inside Bar, Heikin-Ashi, CDL-Z, CDL Pattern
表现 (performance)	3	Drawdown, Log Return, Percent Return

使用示例：

# 拉 K 线同时附加 RSI、MACD、布林带
mtdata-cli data_fetch_candles EURUSD --timeframe H1 --limit 50 --indicators rsi macd bbands

# 按类别搜索指标
mtdata-cli indicators_list --category momentum

# 按名称搜索
mtdata-cli indicators_list --search "moving average"

---

预测方法（71 种）

类别	数量	代表方法
经典	5	theta, naive, drift, fourier_ols, seasonal_naive
ETS/ARIMA	7	holt, holt_winters, arima, sarima, ets
StatsForecast	41	sf_autoarima, sf_ets, sf_theta, sf_ces 等
机器学习	3	mlf_lightgbm, mlf_rf, mlforecast
蒙特卡洛	2	mc_gbm, hmm_mc
预训练大模型	3	chronos2, chronos_bolt, timesfm
sktime	4	sktime_autoarima 等
神经网络	4	nbeatsx, nhits, tft, patchtst（需 ray，Windows 不可用）
其他	2	analog, ensemble

使用示例：

# Theta 方法预测（最轻量，入门首选）
mtdata-cli forecast_generate EURUSD --timeframe H1 --horizon 12 --method theta

# 自回归模型预测
mtdata-cli forecast_generate EURUSD --timeframe H1 --horizon 24 --method sf_autoarima

# 大模型预测（需 GPU 或 CPU 耐心等待）
mtdata-cli forecast_generate EURUSD --timeframe H1 --horizon 12 --method chronos2

---

三种使用方式

1. CLI 命令行

# 安装
pip install -e .

# 验证 MT5 连接
mtdata-cli symbols_list --limit 5

# 拉数据
mtdata-cli data_fetch_candles EURUSD --timeframe H1 --limit 50

# 加指标
mtdata-cli data_fetch_candles EURUSD --timeframe H1 --limit 50 --indicators rsi macd

# 预测
mtdata-cli forecast_generate EURUSD --timeframe H1 --horizon 12 --method theta

# 形态检测
mtdata-cli patterns_detect EURUSD --timeframe H1 --mode candlestick

# 市场状态
mtdata-cli regime_detect EURUSD --timeframe H1 --method bocpd

# 查看所有命令
mtdata-cli --help

# JSON 输出（给脚本用）
mtdata-cli data_fetch_candles EURUSD --timeframe H1 --limit 20 --json

2. MCP（AI 助手）

配置到 Claude Desktop / Cursor / Trae 的 MCP 设置中：

stdio 模式（推荐，客户端自动启动）：

{
  "mcpServers": {
    "mtdata": {
      "command": "mtdata-stdio"
    }
  }
}

SSE 模式（先启动服务，再连接）：

# 终端启动
mtdata-sse

{
  "mcpServers": {
    "mtdata": {
      "url": "http://127.0.0.1:8765/sse"
    }
  }
}

配置后，AI 助手可以直接调用全部 82 个工具。例如：

• "拉 EURUSD 最近 50 根 H1 K 线，附带 RSI 和 MACD"
• "用 Theta 方法预测未来 12 小时"
• "回测一个 RSI 超卖 + MACD 金叉策略"

3. Web UI（图表工作台）

# 安装 Web 依赖
pip install -e ".[web]"

# 构建前端（首次或 UI 更新后）
cd webui && npm ci && npm run build && cd ..

# 启动
mtdata-webapi
# 打开浏览器 → http://127.0.0.1:8766/app/

---

安装指南

完整安装（推荐）

# 1. 创建虚拟环境
conda create -n mtdata python=3.14 -y
conda activate mtdata

# 2. 完整研究栈
pip install -r requirements.txt

# 3. Web UI（可选）
pip install -e ".[web]"
cd webui && npm ci && npm run build && cd ..

分档安装

目标	命令
精简核心（数据+指标+基础分析）	pip install -e .
完整研究栈	pip install -r requirements.txt
仅 Web UI	pip install -e .[web]
经典预测扩展（ARIMA/ML/Optuna）	pip install -e .[forecast-classical]
大模型预测（Chronos/TimesFM）	pip install -e .[forecast-foundation]

---

同步上游更新

本项目 Fork 自 emerzon/mtdata-mcp，当 GitHub 原仓库有更新时，按以下步骤同步到你的 Gitea 仓库。

首次配置上游

# 添加 GitHub 原仓库作为上游（仅需执行一次）
git remote add upstream https://github.com/emerzon/mtdata-mcp.git

拉取并合并最新代码

# 1. 拉取上游所有更新
git fetch upstream

# 2. 合并上游 main 分支到本地 master
git merge upstream/main

# 3. 推送到你的 Gitea 仓库
git push origin master

一键更新命令

git fetch upstream && git merge upstream/main && git push origin master

---

配置

在项目根目录创建 .env 文件：

# ── MT5 连接 ─────────────────────────────────────
# 手动打开 MT5 登录即可，以下可选
# MT5_LOGIN=你的账号
# MT5_PASSWORD=你的密码
# MT5_SERVER=你的经纪商服务器

# ── 时区 ─────────────────────────────────────────
MT5_SERVER_TZ=Europe/Athens     # 经纪商服务器时区（UTC+2/3 用此值）
CLIENT_TZ=Asia/Shanghai          # 本地时区

# ── MCP 服务器 ───────────────────────────────────
MCP_TRANSPORT=sse
FASTMCP_HOST=127.0.0.1
FASTMCP_PORT=8765

# ── Web API ──────────────────────────────────────
WEBAPI_HOST=127.0.0.1
WEBAPI_PORT=8766

# ── 预测 & GPU ───────────────────────────────────
MTDATA_FORECAST_PROCESS_ISOLATION=gpu  # GPU 进程隔离，防止显存泄漏
MTDATA_NF_ACCEL=cpu                     # 神经网络用 CPU（笔记本 GPU 推荐）
CUDA_VISIBLE_DEVICES=0

# ── 交易安全护栏 ────────────────────────────────
MTDATA_TRADE_GUARDRAILS_ENABLED=1
MTDATA_TRADING_ENABLED=1
MTDATA_TRADE_ALLOWED_SYMBOLS=EURUSD,XAUUSD,USDJPY,GBPUSD,USDCAD,NZDUSD,AUDUSD
MTDATA_TRADE_SAFETY_REQUIRE_STOP_LOSS=1
MTDATA_TRADE_MAX_RISK_PCT_OF_EQUITY=1.5

完整配置参考：docs/ENV_VARS.md

---

策略研究 → MQL5 EA 工作流

mtdata 可以和 MQL5 开发无缝衔接：

┌─────────────────────────────────┐
│  ① mtdata 策略研究（Python）     │
│  ├─ 数据探索、形态检测           │
│  ├─ 指标组合回测                 │
│  ├─ 预测模型验证                 │
│  └─ 市场状态分析                 │
└──────────────┬──────────────────┘
               │ 策略逻辑确定
               ▼
┌─────────────────────────────────┐
│  ② 翻译成 MQL5 EA               │
│  ├─ 指标逻辑 → MQL5 内置函数     │
│  ├─ 入场/出场规则 → EA 代码      │
│  ├─ 风控逻辑 → 仓位计算          │
│  └─ 回测比对 → 验证一致性        │
└──────────────┬──────────────────┘
               │
               ▼
┌─────────────────────────────────┐
│  ③ MT5 策略测试器               │
│  ├─ 多品种/多周期回测            │
│  ├─ 优化参数                     │
│  └─ 模拟盘验证                   │
└─────────────────────────────────┘

研究阶段可用工具：

步骤	工具
数据探索	data_fetch_candles + 193 个指标
形态发现	patterns_detect
市场状态	regime_detect
策略回测	strategy_backtest
策略验证	strategy_validate
预测辅助	forecast_generate
TP/SL 优化	forecast_barrier_optimize
风险分析	trade_var_cvar_calculate、trade_stress_test

---

项目结构

mtdata/
├── src/mtdata/
│   ├── bootstrap/          # 运行时初始化、环境变量、工具加载
│   ├── core/               # CLI、MCP/服务器、交易、状态检测、报告
│   │   ├── cli/            # CLI 入口、命令解析、格式化输出
│   │   ├── data/           # K 线、Tick 数据获取
│   │   ├── trading/        # 交易执行、安全护栏、风险计算
│   │   ├── regime/         # 市场状态检测（BOCPD/HMM/MS-AR/PELT）
│   │   └── ...
│   ├── forecast/           # 预测引擎、方法、模型存储、异步任务
│   │   └── methods/        # 71 种预测方法实现
│   ├── patterns/           # K 线/经典/谐波/艾略特波浪检测
│   ├── services/           # MT5 网关、Finviz、期权、新闻
│   ├── shared/             # 共享类型、Schema、常量
│   └── utils/              # 指标、去噪、辅助函数
├── webui/                  # React + Vite 前端
├── docs/                   # 文档（40+ 篇）
├── scripts/                # 独立脚本（回测绘图等）
├── tests/                  # 测试（370+ 个）
└── .env.example            # 环境变量模板

---

文档导览

推荐学习路径：

阶段	阅读
起步	SETUP → GLOSSARY
选择入口	Web UI · CLI · MCP
动手实践	SAMPLE-TRADE · SAMPLE-TRADE-WEBUI
深入预测	FORECAST · METHODS · BACKTESTING
形态状态	REGIMES · PATTERNS
交易安全	TRADING_SAFETY · TRADING_RISK
进阶玩法	SAMPLE-TRADE-ADVANCED · EXAMPLE

---

快速上手命令

# 1. 验证连接
mtdata-cli symbols_list --limit 5

# 2. 拉 K 线
mtdata-cli data_fetch_candles EURUSD --timeframe H1 --limit 50

# 3. 带指标拉数据
mtdata-cli data_fetch_candles EURUSD --timeframe H1 --limit 50 --indicators rsi macd bbands

# 4. 基础预测
mtdata-cli forecast_generate EURUSD --timeframe H1 --horizon 12 --method theta

# 5. 形态检测
mtdata-cli patterns_detect EURUSD --timeframe H1 --mode candlestick

# 6. 市场状态
mtdata-cli regime_detect EURUSD --timeframe H1 --method bocpd

# 7. 策略回测
mtdata-cli strategy_backtest EURUSD --timeframe H1 --lookback 500 \
  --entry-long "rsi(14) < 30" --cost-model fixed --spread-bps 1.5

# 8. 生成报告
mtdata-cli report_generate EURUSD --timeframe H1 --template basic

# 9. 查看新闻
mtdata-cli news EURUSD

# 10. 查看所有工具
mtdata-cli tools_list

---

许可证

MIT

---

致谢

本项目是 emerzon/mt-data-mcp 的中文文档补充。