内容
# mt5-mcp-server
AI に **MetaTrader 5 的策略测试器** 进行自动化操作的 **MCP 服务器**（Python / FastMCP / stdio）。
Claude Code 等 MCP 客户端发送指令，例如“用此EA在EURUSD H1上进行2024年回测并优化”，
`.ini` 生成 → `terminal64.exe` 启动 → 等待完成 → 报告解析 → 结果结构化，全部自动完成。
> **仅支持 Windows**（MT5 Strategy Tester 仅支持 Windows）。Python 3.10+。
## 工具列表
| 工具 | 概要 |
|---|---|
| `mt5_info` | 检测默认 MT5、数据文件夹、构建版本、EA 数量及是否正在运行（用于安装验证） |
| `list_mt5_terminals` | 列出所有检测到的 MT5 安装（按券商分类） |
| `list_eas` | 列出 `MQL5/Experts/` 目录下的 `.ex5` 文件（将 `rel_path` 传递给 `ea`） |
| `run_backtest` | 进行单次回测 → 返回净利/PF/DD/胜率/交易次数等 |
| `optimize` | 进行遗传优化 → 获取最佳 N 个参数（通过 `min_trades` 设置交易次数下限） |
| `run_forward_test` | 使用固定参数进行 OOS（样本外）测试 |
| `full_pipeline` | 一站式完成 IS 优化 → OOS 验证 → 过度优化检查 |
| `send_to_iwaraizer` | 将 MT5 回测的所有交易明细传递给岩ライザーFX进行分析（keepdata 输入） |
## 环境要求
- **Windows 10/11**
- **Python 3.10+**
- **已安装 MetaTrader 5**，**目标账户已登录**，且测试品种的**历史数据已下载**。
（如果未登录/无历史数据，报告将显示，但 `history_quality=0%` 和 0 交易结果）
## 安装
```powershell
# 使用 pipx（推荐，隔离安装）
pipx install git+https://github.com/iwanao513/mt5-mcp-server
# 发布到 PyPI 后：pipx install mt5-mcp-server
# 使用 uvx（零安装执行）
uvx --from git+https://github.com/iwanao513/mt5-mcp-server mt5-mcp-server
# 发布到 PyPI 后：uvx mt5-mcp-server
# 从源码安装（开发）
git clone https://github.com/iwanao513/mt5-mcp-server
cd mt5-mcp-server
python -m venv .venv
.\.venv\Scripts\python -m pip install -e .
```
无论哪种情况，`mt5-mcp-server` 可执行文件都会进入 PATH（或 venv）。
## 注册到 MCP 客户端
这是 stdio 服务器。所有客户端的 `command`/`args` 格式相同，仅配置不同。
**Claude Code**
```powershell
claude mcp add mt5 -- mt5-mcp-server
# 如果仅在 venv 中安装，请传递执行文件的完整路径：
# claude mcp add mt5 -- "<REPO>\.venv\Scripts\mt5-mcp-server.exe"
```
**Claude Desktop**（`%APPDATA%\Claude\claude_desktop_config.json`）
```json
{ "mcpServers": { "mt5": { "command": "mt5-mcp-server", "args": [] } } }
```
**Cursor**（`.cursor/mcp.json`）/ **Windsurf**（`~/.codeium/windsurf/mcp_config.json`）/ **VS Code**（`.vscode/mcp.json` 使用 `servers` 键）也可以使用相同的 `command: "mt5-mcp-server"` 注册。
确认：`claude mcp list` / `claude mcp get mt5` / 客户端内 `/mcp`。
## 使用方法
1. 使用 `mt5_info()` 确认检测（如果 `is_running` 为 true，则关闭目标 MT5）。
2. 使用 `list_eas("moving")` 获取 EA 的 `rel_path`。
3. 执行 `run_backtest(ea="Examples\\Moving Average\\Moving Average.ex5", symbol="EURUSD", from_date="2024.01.01", to_date="2024.06.30", period="H1")`。
4. 执行 `optimize(ea=..., symbol="EURUSD", from_date="2024.01.01", to_date="2024.04.30", param_ranges={"MovingPeriod":[8,40,2],"MovingShift":[0,10,2]}, min_trades=40)`。
5. 使用 `full_pipeline(...)` 一站式完成 IS 优化 → OOS 验证 → 过度优化检查。
> 如果 `list_eas` 为空，请在 MetaEditor 中编译一次 EA（位于 `MQL5/Experts/Examples` 或任意 EA）。**仅编译后的 `.ex5` 可用于测试**。
## 选择 MT5（支持多安装）
使用 `list_mt5_terminals()` 确认候选 MT5（按券商和构建版本分类），并通过路径指定目标 MT5。
- 工具参数 `terminal_path`（每次调用时）：例如 `run_backtest(..., terminal_path="C:\\Program Files\\XMTrading MT5\\terminal64.exe")`
- 默认固定：用户设置（如下）的 `terminal_path`
如果未指定，则按以下顺序自动检测：
1. 配置文件 → `C:\Program Files\MetaTrader 5`（如果存在）→ 注册表（包括券商版本）
## 配置
配置按以下顺序读取和合并，后者优先：
1. 仓库自带的 `config/mt5_config.json`（开发模板，全为 null）
2. **用户设置 `%APPDATA%\mt5-mcp-server\mt5_config.json`**（安装使用此处）/ 同目录下的 `mt5_config.local.json`
3. 环境变量 `MT5_MCP_CONFIG`（任意 JSON 文件路径）
| 键 | 默认值 | 说明 |
|---|---|---|
| `terminal_path` | 自动检测 | `terminal64.exe` 的完整路径（或父目录） |
| `data_folder` | 自动检测 | 从 `origin.txt` 反向查找 |
| `default_deposit`/`default_currency`/`default_leverage` | 10000/USD/1:100 | |
| `default_model` | 1 | 0=每笔成交, 1=1分钟OHLC, 2=开盘价, 4=实际成交 |
| `backtest_timeout_sec`/`optimization_timeout_sec` | 1200/7200 | |
| `login`/`password`/`server` | （未设置） | 用于无头自动登录（如下） |
### 无头自动登录（也自动下载历史数据）
如果使用未登录的 MT5，请在用户设置中添加**账户信息**，通过 `.ini` 的 `[Common]` 部分在启动时自动登录，并自动下载缺失的历史数据：
```json
{ "terminal_path": "C:\\Program Files\\XMTrading MT5\\terminal64.exe",
"login": 12345678, "password": "模拟账户密码", "server": "XMTrading-Demo" }
```
> ⚠️ **强烈建议使用模拟账户**（不要明文存储真实账户密码）。`mt5_config.local.json` 已被 gitignore。**请勿在 tracked 的 `mt5_config.json` 中写入 `terminal_path`/`login`/`password`**（防止提交事故）。
## 避免过度优化
`full_pipeline` **分割 IS（优化）/ OOS（验证）期间**，如果 OOS 中 PF 下降、亏损或交易太少，则触发 `overfit_warning`。
通过 `min_trades` 设置**交易次数下限**，排除优化后参数的少数侥幸获胜。
优化参数应**保持较少**以确保安全。
## 岩ライザーFX（Iwaraizar FX）集成
使用 `send_to_iwaraizer` 将 MT5 回测的**所有交易明细**传递给岩ライザーFX 桌面应用程序进行分析。
1. 执行 `run_backtest(...)`（返回 `report_path`）。
2. 执行 `send_to_iwaraizer(report_path=<其 .htm>, title="My EA EURUSD", parameter="MovingPeriod=8; MovingShift=4")`。
- 从报告的 **Deals（成交）表**中**重建交易（FIFO）**（输入/输出对），并添加到岩ライザーFX 的
`%APPDATA%\iwaraizar_fx_public\keepdata\Contents.json` 中作为 **1 个数据集**（自动备份 `.bak`）。
3. 打开岩ライザーFX → 添加数据集 → 执行计算，查看图表/统计数据（PF/DD/胜率/月度等）。
- 应用程序侧**无需修改**（使用 `fs.watch` 自动检测）。可以通过 `keepdata_dir` 参数覆盖保存路径。
- 验证：确认 146 笔交易的重建结果与“最终余额 - 初始余额 = 报告净利”一致。
## 故障排除
| 症状 | 原因/解决方法 |
|---|---|
| `terminal64.exe not found` | MT5 未检测到。使用 `list_mt5_terminals()` 进行确认，或在设置中指定 `terminal_path` |
| `MetaTrader 5 is already running` | 目标 MT5 已运行。关闭或设置 `close_running=true` |
| `no report produced` / `history_quality=0%` / 0 交易 | 未登录或无历史数据。登录 MT5 账户并下载历史数据（或在设置中添加 login/password/server） |
| `authorization ... (Old version)` | 该终端的构建版本过旧，被服务器拒绝。更新终端或使用最新构建版本 |
| `list_eas` 为空 | 无 `.ex5` 文件。使用 MetaEditor 编译 EA |
## 安全与免责
- 回测/交易存在风险。本工具仅用于验证辅助，不保证结果或策略的优劣。
- `close_running` **会关闭目标 MT5**（默认为 false，需显式开启）。
- stdio 本地服务器，无外部公开。认证信息仅在本地设置中处理，切勿提交。
## License
MIT License — 请参阅 [LICENSE](LICENSE)。
