MT5-Quant

MT5-Quant

适用于 macOS/Linux 上 MT5 策略开发的 MCP 服务。 提供 89 个工具，可用于编译、回测、分析、优化、调试崩溃问题，以及管理 MQL5 Expert Advisors——无需 Windows。

You: "Backtest MyEA Jan-Mar, what caused the February drawdown?"

Claude: [compile → clean → backtest → analyze 1,847 deals]
        → Feb 14: BUY grid at L6, locking lot 1.75× base
        → Cutloss fired 17 points later
        → Recommendation: cap locking multiplier to ≤1.2×

为什么选择 MT5-Quant

专注于： 回测管理、报告和分析——这些是 MT5 本身不提供的功能。

	MT5-Quant	其他方案
平台	原生支持 macOS/Linux	仅限 Windows
回测流水线	✅ 完整（编译 → 运行 → 分析）	✅ 通过 MT5 Python package
交易级分析	✅ 19 个维度，由数据库支持	❌
报告管理	✅ SQLite（报告 + 交易）+ 搜索 + 历史记录	❌
MQL5 编译	✅ 无头模式（通过 Wine 使用 MetaEditor，无 GUI）	⚠️ 通过 GUI 或终端
优化	✅ 后台运行 + 结果解析 + .set 生成	⚠️ 仅终端运行，不支持解析
崩溃调试	✅ Wine/MT5 诊断	❌

其他方案通常在 Windows 上运行，使用 MetaTrader5 Python package 提供完整的终端操作。MT5-Quant 填补了这一空白：整理回测报告、提取交易级洞察，以及管理优化工作流——MT5 及其 Python API 均未原生提供这些功能。

快速入门

安装 MT5-Quant

选项 A — Cargo（推荐，需要 Rust 工具链）

cargo install mt5-quant --locked

选项 B — 预编译二进制文件（无需工具链）

# macOS Apple Silicon
curl -LO https://github.com/masdevid/mt5-quant/releases/latest/download/mcp-mt5-quant-macos-arm64.tar.gz
tar xzf mcp-mt5-quant-macos-arm64.tar.gz   # → mcp-mt5-quant-macos/mt5-quant

# Linux x64
curl -LO https://github.com/masdevid/mt5-quant/releases/latest/download/mcp-mt5-quant-linux-x64.tar.gz
tar xzf mcp-mt5-quant-linux-x64.tar.gz     # → mcp-mt5-quant-linux/mt5-quant

将二进制文件移至 PATH 中的某个位置（例如 /usr/local/bin 或 ~/.local/bin），以便客户端可以将其作为 mt5-quant 启动。

选项 C — 注册到 LLM 客户端（复制粘贴）

Claude Code

claude mcp add mt5-quant -- mt5-quant --stdio

Claude Desktop — ~/Library/Application Support/Claude/claude_desktop_config.json

{ "mcpServers": { "mt5-quant": { "command": "mt5-quant", "args": ["--stdio"] } } }

Cursor — .cursor/mcp.json（JSON 结构与 Claude Desktop 相同）

{ "mcpServers": { "mt5-quant": { "command": "mt5-quant", "args": ["--stdio"] } } }

opencode — .opencode/opencode.jsonc

{ "mcp": { "mt5-quant": { "type": "local", "command": ["mt5-quant", "--stdio"], "enabled": true } } }

Codex CLI — ~/.codex/config.toml

[mcp_servers.mt5-quant]
command = "mt5-quant"
args = ["--stdio"]

然后完成设置（自动检测 Wine 和 MT5 路径）：

bash scripts/setup.sh

提示： 也可以直接让你的 LLM 编码 Agent 完成上述所有操作： “请从 https://github.com/masdevid/mt5-quant 安装 mt5-quant——下载或构建它，运行其 scripts/setup.sh 自动检测 Wine 和 MT5 路径，并将其注册为 MCP 服务。”

首次回测

Run a backtest on MyEA from 2025.01.01 to 2025.03.31

AI 将运行完整流水线：编译 → 清理缓存 → 回测 → 提取 → 分析。

MCP 工具（89 个）

核心工作流

工具	描述
run_backtest	完整流程：编译 → 清理 → 回测 → 提取 → 分析
run_backtest_quick	使用预编译 EA 快速回测（跳过编译）
run_backtest_only	仅回测——只提取原始交易，不进行分析
launch_backtest	即发即忘：启动 MT5 回测，并轮询直至完成
get_backtest_status	轮询正在运行的回测状态（MT5 是否运行、是否找到报告、已用时间）
run_optimization	遗传优化（后台运行，立即返回）
get_optimization_results	MT5 完成后解析优化结果
list_jobs	列出所有优化任务及其状态
analyze_report	从任意报告目录读取 analysis.json
compare_baseline	将报告与基准进行比较，并给出胜负结论
compile_ea	通过 MetaEditor 编译 MQL5 EA
list_experts	列出 MQL5/Experts 目录中的所有 EA
list_indicators	列出 MQL5/Indicators 目录中的所有指标
list_scripts	列出 MQL5/Scripts 目录中的所有脚本
healthcheck	快速检查服务健康状态
list_symbols	列出 MT5 终端中所有可用的交易品种

细粒度分析（单项分析）

工具	描述
analyze_monthly_pnl	仅分析每月盈亏明细
analyze_drawdown_events	仅分析回撤事件及原因
analyze_top_losses	仅分析亏损最大的交易
analyze_loss_sequences	仅分析连续亏损模式
analyze_position_pairs	分析持仓时间与盈亏配对情况
analyze_direction_bias	分析买入与卖出的表现
analyze_streaks	分析连胜/连败情况
analyze_concurrent_peak	分析同时持仓数量峰值

可使用这些工具进行针对性分析，也可使用 analyze_report 一次性运行全部分析。

交易级分析（新增）

工具	描述
list_deals	根据筛选条件（类型、利润范围、交易量、日期）列出单笔交易
search_deals_by_comment	在交易备注中进行全文搜索（例如，“Layer #3”）
search_deals_by_magic	按 EA 魔术编号筛选交易
analyze_profit_distribution	盈利直方图：小额/中额/大额盈利和亏损
analyze_time_performance	按一天中的时段和星期几分析表现
analyze_hold_time_distribution	持仓时间区间及其与利润的相关性
analyze_layer_performance	根据备注分析网格/马丁格尔层级表现
analyze_volume_vs_profit	交易量相关性及按手数划分的表现
analyze_costs	分析佣金和隔夜利息对盈利能力的影响
analyze_efficiency	每小时/每天利润、年化回报、交易频率

监控

工具	描述
verify_setup	检查 Wine/MT5 路径、Wine 版本以及 EA/设置文件数量
get_optimization_status	检查后台优化任务的实时状态
list_jobs	一次调用即可查看所有优化任务及其简要状态

报告与日志

工具	描述
list_reports	显示所有运行记录及关键指标的精简表格，无需完整分析
get_latest_report	获取最近的报告，可选择包含权益图表
search_reports	按 EA、品种、日期范围或利润条件查找报告
get_report_by_id	按 ID 获取指定报告及权益图表
get_reports_summary	汇总统计：数量、平均值、通过率
get_best_reports	按任意指标（盈利因子、回撤等）排序，获取排名前 N 的报告
search_reports_by_tags	按标签查找报告
search_reports_by_date_range	按回测日期范围查询
search_reports_by_notes	在报告备注中进行全文搜索
get_reports_by_set_file	查找所有使用指定 .set 文件的报告
get_comparable_reports	查找可比较的报告（EA、品种和时间周期相同）
tail_log	读取任意日志的最后 N 行；使用 filter=errors 仅查看失败记录
prune_reports	删除旧报告目录，保留最近 N 个（跳过 _opt 目录）
promote_to_baseline	将历史记录或报告写入 baseline.json，供 compare_baseline 使用

历史记录与基准

工具	描述
archive_report	将一个报告目录转换为 backtest_history.json 中的精简 JSON 条目，可选择删除源目录
archive_all_reports	批量归档所有报告目录，然后可选择删除；安全保留最新的 N 个
get_history	使用筛选条件（EA、品种、判定结果、利润、DD）查询历史记录，并提供排序选项
annotate_history	为任意历史记录附加判定结果、备注或标签

缓存管理

工具	描述
cache_status	按品种细分 MT5 测试器缓存大小，清理前可先检查
clean_cache	删除测试器缓存文件；支持按品种清理和 dry_run

预检与验证

工具	描述
get_active_account	获取当前 MT5 账户会话信息（登录名、服务、可用品种）
check_symbol_data_status	验证品种在指定日期范围内是否有足够的历史数据
check_mt5_status	检查是否已安装 MT5 终端且准备就绪
validate_ea_syntax	在完整编译前进行语法检查

调试与诊断（新增）

工具	描述
diagnose_wine	检查 Wine 安装情况、版本和前缀健康状态
get_mt5_logs	获取 MT5 终端、测试器或 MetaEditor 日志，并进行筛选
search_mt5_errors	搜索日志中的错误模式（崩溃、异常、访问冲突）
check_mt5_process	检查 MT5 进程是否正在运行，并获取 PID、CPU 和内存使用情况
kill_mt5_process	结束卡住的 MT5 进程（对 wineserver 使用 force=true）
check_system_resources	检查磁盘空间、内存和 CPU 可用情况
validate_mt5_config	验证 terminal.ini 和测试器配置文件
get_wine_prefix_info	获取 Wine 前缀详情：Windows 版本、已安装程序和注册表
get_backtest_crash_info	调查回测失败：不完整标记、缺失的 deals.csv 和错误
check_update	检查是否有更新版本的 MT5-Quant
update	将 MT5-Quant 更新到最新版本

项目管理

工具	描述
init_project	使用模板（scalper/swing/grid/basic）搭建新的 MQL5 项目框架
create_set_template	根据 EA 输入变量生成 .set 参数文件
export_report	将回测报告导出为 CSV、JSON 或 Markdown

历史记录与比较

工具	描述
get_backtest_history	列出 EA/品种的所有回测及汇总指标
compare_backtests	并排比较 2 个或更多回测结果，并进行分析

.set 文件 — 读取 / 写入

工具	描述
list_set_files	测试器配置文件目录中的所有 .set 文件，包含扫描统计信息和组合数量
read_set_file	解析 UTF-16LE .set 文件 → 结构化 JSON 参数
write_set_file	将完整参数字典写入 UTF-16LE .set 文件，并设置 chmod 444
patch_set_file	就地更新指定参数并返回差异 — 替代读取→编辑→写入流程
clone_set_file	将 .set 文件复制到新路径，并可在一次调用中选择性覆盖参数

.set 文件 — 分析与生成

工具	描述
describe_sweep	扫描参数、取值数量和优化组合总数
diff_set_files	并排比较两个 .set 文件 — 仅返回已更改的参数
set_from_optimization	根据 get_optimization_results 参数生成精简的回测 .set 文件；可选择缩小扫描范围

搜索与发现

工具	描述
search_experts	按名称模式搜索所有目录中的 EA
search_indicators	按名称模式搜索指标
search_scripts	按名称模式搜索脚本
copy_indicator_to_project	将指标复制到项目目录
copy_script_to_project	将脚本复制到项目目录

完整架构：docs/MCP_TOOLS.md

故障排除

先让你的大模型运行 verify_setup — 它会检查所有路径并返回可操作的提示。

如果回测／编译／优化期间发生崩溃或无法解释的故障：

• diagnose_wine — 检查 Wine 安装和前缀健康状况
• search_mt5_errors — 在日志中查找崩溃原因
• check_mt5_process + kill_mt5_process — 检测并终止卡住的进程
• get_backtest_crash_info — 调查失败的回测报告

完整故障排除指南 →

文档

文档	描述
QUICKSTART	分步完成安装、设置和首次回测
MCP_TOOLS	所有 90 个工具的完整输入／输出架构
CONFIG	配置参考（config/mt5-quant.yaml）
ARCHITECTURE	设计原则和内部模块布局
REMOTE_AGENTS	通过 Wine 将优化任务分发到 Linux Agent
TROUBLESHOOTING	针对 Wine、MT5 和回测的平台特定修复方法

完整索引及阅读顺序：docs/INDEX.md

---

致谢

MT5-Quant 建立在众多杰出开源项目的基础之上：

• Rust — 让零成本抽象、内存安全和无惧并发切实可行的语言
• Tokio — 为所有并发操作提供动力的异步运行时
• Wine — 无需 Windows 许可证即可在 macOS 和 Linux 上运行 MT5
• MetaTrader 5 — MetaQuotes 的交易平台（MetaQuotes Software Corp. 的商标）
• rusqlite — 易于使用的 Rust SQLite 绑定
• serde — 让配置和报告处理变得轻松的序列化框架
• scraper — 用于提取 MT5 报告的 HTML 解析工具
• tempfile — 安全的临时文件处理工具

特别感谢 Anthropic 的 Model Context Protocol（MCP）团队制定了这项标准，让 AI 驱动的开发工作流成为可能。

免责声明

不构成财务建议。 MT5-Quant 是一款用于算法交易策略开发和分析的工具，不提供投资建议或交易推荐，也不保证盈利。所有回测结果均为历史模拟，不保证未来表现。

风险自负。 交易金融工具存在重大亏损风险。MT5-Quant 的作者和贡献者不对以下情况承担任何责任：

• 使用此工具开发或测试的策略造成的交易亏损
• 回测操作导致的数据丢失或损坏
• 程序缺陷、错误或不准确的分析结果
• 系统崩溃、Wine 兼容性问题或 MT5 故障

软件保证。 本软件按“原样”提供，不提供任何明示或默示的保证，包括但不限于适销性、特定用途适用性或不侵权保证。完整条款请参阅 LICENSE。

第三方软件。 MT5-Quant 会与 MetaTrader 5、Wine 和其他第三方软件交互。用户有责任遵守这些依赖项适用的所有许可和服务条款。MetaTrader 是 MetaQuotes Software Corp. 的商标。MT5-Quant 与 MetaQuotes 没有关联，也未获得其认可或赞助。

法规合规。 用户有责任确保其交易活动符合所在司法辖区适用的金融法规。在某些地区，自动交易可能受到限制或需要取得许可。

许可证

MIT

---