内容
# MBT — MT5 回测工具箱（MCP for Claude 代码）
```
███╗ ███╗██████╗ ████████╗
████╗ ████║██╔══██╗╚══██╔══╝
██╔████╔██║██████╔╝ ██║
██║╚██╔╝██║██╔══██╗ ██║
██║ ╚═╝ ██║██████╔╝ ██║
╚═╝ ╚═╝╚═════╝ ╚═╝
MT5 回测工具箱 · 在真实 K 线上重放真实信号
╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴
```
**通过与 Claude AI 对话，回测、构建和验证 MetaTrader 5 策略，无需脚本，无需 Python 重实现，仅需真实信号和真实经纪商数据。**
**要求：** Python 3.9+ · MetaTrader 5（Windows，或通过 Wine 运行于 Linux/macOS）· Claude 代码
将一个包含宏指令的文件包含到您的指标中，MBT 让您通过 Claude 完成所有操作：
- **回测您的指标的真实信号** — 在真实经纪商 K 线上重放，并附带 HTML 报告。
- **无需图表运行您的指标** — 无需附加图表；Claude 计算并记录信号。
- **构建、测试和验证一个专家顾问** — 编译它，运行 MT5 的真实策略测试器，并证明它仍然符合策略。
核心原则：**MBT 永远不会在 Python 中重新计算您的指标。** 您的指标记录它生成的信号；MBT 读取这些真实信号并重放真实经纪商价格 K 线向前，查看每个交易是否达到止损或目标。您回测的是您的指标实际绘制的内容。
---
## 我们解决的问题
我使用 Claude 编写 MQL5 指标。为了验证指标是否正确计算，下一步自然是让 Claude 编写一个 Python 脚本来检查逻辑。问题是，如果 Claude 在 MQL5 代码中犯了错误，那么它很可能在验证的 Python 版本中也犯了相同的错误。您没有获得独立的检查 — 您只是确认 Claude 自身的一致性。原始 MQL5 代码中的任何错误仍然是不可见的。
解决方案是让指标记录其自身的决策 — 每个信号的入口、止损、目标价位和上下文。现在您不是测试复制品。您正在测试真实的东西。
这就是 MBT 的基础。指标记录它实际执行的操作。MBT 读取这些日志，获取真实经纪商价格 K 线，并重放每个交易向前 — 验证信号是否正确生成，以及止损或目标价位是否首先被击中。**您回测的是您的指标实际绘制的内容 — 而不是 Python 近似值。**
---
## 工作原理
```
您的 MT5 指标 MBT（此工具箱）
┌──────────────────┐ ┌────────────────────────────┐
│ #include │ writes │ reads signals.csv │
│ <SignalLogger> ├─ signals.csv ┤ │
│ LogSignal(...) │ │ replays real MT5 bars │
└──────────────────┘ │ forward → WIN / LOSS / OPEN │
│ │
│ tools exposed to Claude: │
│ get_ohlcv │
│ get_signals │
│ run_indicator (headless) │
│ backtest (+ HTML report) │
│ validate_signals │
└────────────────────────────┘
```
这是上述指标-回测循环。MBT 还驱动 MT5 的自身工具链来**构建、测试和验证一个专家顾问**（`compile_ea`、`run_strategy_tester`、`signal_parity`）— 参见 [构建、测试和验证专家顾问](#构建测试和验证专家顾问)。
---
## 安装
> **新手？** 将 MBT 仓库 URL 粘贴到 Claude Code 中并说：
> `"Clone this repo and set up the MBT MCP server for me"`
> Claude 将克隆它，运行安装程序，并注册服务器 — 只需编辑 `config.yaml` 即可。
```bash
cd MBT
python install.py
```
这安装依赖项，创建 `config.yaml`，将 `SignalLogger.mqh` 复制到您的 MT5 `Include` 文件夹中，将无头主机 EA `MBT_IndicatorHost.mq5` 复制到 `Experts` 文件夹中，并打印注册 MCP 服务器的命令。
然后编辑 **config.yaml**：
```yaml
mt5_path: "C:/.../terminal64.exe" # 您的指标运行的终端
signal_file: "signals.csv" # 必须与指标中的 SignalLogFile 匹配
default_symbol: "EURUSD"
default_timeframe: "1h"
ambiguous_bar: "loss" # 保守
```
> 运行指标或测试 EA 还需要 **`tester:`** 块（终端路径等）— 从 `config.example.yaml` 复制并填写。
> 普通指标重放回测不需要它。
注册服务器（安装程序打印）：
```bash
claude mcp add mbt python "/abs/path/to/MBT/mcp_server.py"
```
---
## 在 Linux / macOS 上运行（通过 Wine）
MetaTrader 5 和其 Python 包仅支持 Windows — 但 MBT 通过 [Wine](https://www.winehq.org/) 在 Linux 和 macOS 上运行良好。回测结果与 Windows 相同；仅设置有所不同。
**一个规则：** `MetaTrader5` Python 包通过 Windows DLL 与终端通信，因此它必须在与 MT5 相同的 Wine 前缀的 Python 下运行 — 而不是您的系统 Python。系统 `python3` 将始终因 `ModuleNotFoundError: No module named 'MetaTrader5'` 而失败。
> 此规则仅适用于**重放引擎**（`backtest`、`get_ohlcv`、`get_signals` — 它们通过 `MetaTrader5` 包读取实时数据）。基于测试器的工具（`run_indicator`、`run_strategy_tester`、`compile_ea`）根本不使用该包 — 它们直接启动终端/MetaEditor。在 Linux/macOS 上，它们只需要 `launcher: "wine"` 在 `tester:` 块中（安装程序为您默认设置），它们可以在系统 Python 下运行良好。
1. **在 Wine 下安装 MT5** — 从您的经纪商（或 MetaQuotes）下载安装程序并使用 Wine 运行。它位于 Wine 前缀中，例如 `~/.wine/drive_c/Program Files/MetaTrader 5/terminal64.exe`。
2. **在同一个 Wine 前缀中安装 Windows Python *并添加依赖项：**
```bash
wine /path/to/wine/python.exe -m pip install MetaTrader5 numpy PyYAML mcp
```
3. **在 Wine 路径中指向 `config.yaml`。** 使用 Windows 样式的终端路径和以 `Z:` 映射的绝对路径（Wine 将 `Z:` 映射到 `/`）：
```yaml
mt5_path: "C:/Program Files/MetaTrader 5/terminal64.exe"
signal_file: "Z:/home/you/path/to/signals.csv"
```
4. **通过 Wine Python 运行所有内容：**
```bash
wine /path/to/wine/python.exe mcp_server.py # MCP 服务器
wine /path/to/wine/python.exe run_report.py # 一次性回测
```
> **提示：** `SignalLogger.mqh` 位于 Wine 前缀的 `MQL5/Include` 文件夹中 — 如果 `install.py` 找不到它，请手动复制它。其他所有内容（Python 核心、回测引擎、HTML 报告）均无需修改。
---
## 将日志添加到您的指标
```mql5
#include <SignalLogger.mqh>
// 在 OnInit（或完全重新计算）中，以便日志与图表匹配：
ResetSignalLog();
// 当您的买入/卖出条件在 K 线 `shift` 上为真时：
LogSignal(shift, true, entry, sl, tp, "TRENDING"); // 买入
LogSignal(shift, false, entry, sl, tp, "TRENDING"); // 卖出
```
`regime` 是可选的 — 如果您不使用它，请传递 `""`。当存在时，回测报告按制度分解结果。
编译它 — 就是这样。从这里，您有两种方法让指标记录其信号：
- **无头（推荐）：** 请求 Claude 运行它 — `run_indicator` 在您选择的日期范围内计算指标，无需附加图表并自动记录信号。无需附加图表。
- **在图表上：** 将编译后的指标附加到图表上，如同平常一样；它在运行时实时写入 `signals.csv`。
无论哪种方式，您最终都会得到相同的文件，`backtest` 工具会读取该文件。
---
## 使用它
只需在 Claude Code 中描述您想要的内容 — Claude 会自动选择合适的工具。
**运行您的指标并回测它 — 无需图表：**
> "在 XAUUSD H1 上运行我的 RegimePlusePro 指标，持续 3 年，然后回测它"
Claude 运行指标（无头计算整个范围并记录其自身的信号），然后重放这些信号到真实的 K 线上，并为您提供指标 + HTML 报告。您无需打开图表。（第一次，Claude 将为您完成任何一次性设置。）
**或者回测您已经拥有的信号**（来自以前的运行或实时运行在图表上的指标）：
> "回测我的信号"
> "自 2026-01-01 以来回测我的信号并给我 HTML 报告"
> "验证我的信号文件"
> "获取最近的 300 个 EURUSD 1h K 线"
`backtest` 工具返回完整的指标并写入 `reports/` 中的 HTML 报告（带有权益曲线）。
### 构建、测试和验证专家顾问
一旦您有了一个 EA（或请求 Claude 从您的指标构建一个），MBT 让您编译它，通过 MT5 的真实测试器运行它，并确认它与您的指标交易完全相同 — 所有这些都通过与 Claude 对话：
**步骤 1 — 编译和修复：**
> "检查我的 EA 错误"
> "修复错误并再次编译"
Claude 将使用 MetaEditor 编译，读取结构化错误，修复代码并重新编译，直到它干净为止 — 无需您打开 MetaEditor。
**步骤 2 — 回测真实 EA 代码：**
> "运行我的 EA 在 XAUUSD H1 从 2018 年至今的策略测试器回测"
这运行 MT5 自身的无头策略测试器 — 真实点差、掉期和执行 — 而不是 Python 模拟。返回与 MT5 策略测试器报告中相同的指标。
**步骤 3 — 将 EA 结果与您的指标进行交叉检查：**
> "比较我的 EA 结果与我的指标回测 — 它们是否匹配？"
如果您已经运行了指标的信号重放回测，它会检查 EA 是否在相同的 K 线上产生相同的交易。第一个分歧的 K 线将被精确定位，以便您准确知道移植在哪里出现偏差。
### 无头运行和 EA 工具的设置
上述纯英语提示是您日常所需的 — 这是一次性设置（Claude 可以完成所有这些）：
- **`tester:`** 块 — 两个无头 `run_indicator` 和 EA 工具（`compile_ea`、`run_strategy_tester`、`signal_parity`）都需要它填写；从 `config.example.yaml` 复制它。普通的指标重放回测不需要它。
- **主机 EA** — `run_indicator` 通过捆绑的辅助 EA 加载您的指标，`MBT_IndicatorHost.mq5`。`install.py` 将其复制到 `MQL5/Experts`；它必须编译一次（只需请求 Claude 编译 MBT 指标主机）。
- **指标日志记录** — 指标必须通过 `SignalLogger.mqh` 记录（自定义记录器仅写入终端的本地 `Files` 文件夹，对无头运行不可见）。无头运行使用指标的**默认**输入。
- **Linux/macOS** — 这些工具通过 Wine 直接启动终端；设置 `launcher: "wine"`（安装程序默认为它）和 `portable: true` 如果安装保留其数据在 exe 旁边。
---
## 报告中包含的内容
- 总交易 · 胜利 · 失败 · 开仓
- 胜率 · 利润因子 · 预期值（平均 R）
- 净结果 · 最大回撤（以 R 为单位）
- 平均获胜 / 损失 · 最大获胜 / 损失连胜
- 按制度分类
- 权益曲线（累积 R）
所有内容均以 **R 单位**（1R = 每个交易的风险，入口 → 止损），因此结果可以跨符号、时间框架和账户大小进行干净的比较。
---
## 信号 CSV 格式
`SignalLogger.mqh` 编写此标准标题：
```
time,symbol,timeframe,direction,entry,sl,tp,regime
```
任何匹配此格式的文件都有效 — MBT 是指标无关的。额外的列将被忽略，如果没有头部，旧式的文件仍然会被读取，如果其第一列是时间戳。
---
## 工具（MCP）
| 工具 | 用途 |
|------|---------|
| `ping` | 检查 MT5 是否正在运行且可达 |
| `get_ohlcv` | 任何符号/时间框架的实时 OHLCV K 线（最大 2000） |
| `get_signals` | 读取您指标记录的信号 |
| `backtest` | 重放 + 完整指标 + HTML 报告（需要互联网访问图表） |
| `validate_signals` | 检查每个信号的 SL/TP 几何形状 |
| `get_config` | 显示活跃的终端 + 信号文件 |
| `compile_ea` | 使用 MetaEditor 编译 EA/指标 → 结构化错误/警告 |
| `run_indicator` | 无头运行指标以记录其信号 — 无需图表附件 |
| `run_strategy_tester` | 在 EA 上运行 MT5 的真实无头策略测试器 → 指标 + 报告 |
| `signal_parity` | 差异两个信号集并报告第一个分歧 |
> **注意：** HTML 报告写入您的机器上的 `reports/` 并在浏览器中打开。Claude 无法直接打开它 — 它会为您提供文件路径。
---
## 示例
`examples/` 包含一些示例信号 CSV 文件，您可以使用它们在不附加指标的情况下尝试 MBT。将 `signal_file` 在 `config.yaml` 中指向其中任何一个：
```yaml
signal_file: "C:/abs/path/to/MBT/examples/test_signals.csv"
```
---
## 研究脚本
`scripts/` 包含一些用于策略开发的一次性分析脚本。它们不是核心工具包的一部分，没有文档 — 将它们视为参考资料，而不是用户工具。
---
## 在 YouTube 上构建
该工具箱是在 [FX David](https://www.youtube.com/@fxdavid9392) 的 YouTube 上直播构建、验证和回测 MT5 指标与 Claude AI 的系列节目中构建的。
