Devid HWMT5-Quant
MCP server for MT5 strategy development on macOS/Linux. 57 tools to compile, backtest, analyze, optimize, and manage MQL5 Expert Advisors — no Windows required.
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×
Why MT5-Quant
| MT5-Quant | Other MT5 MCPs | QuantConnect | |
|---|---|---|---|
| Backtest pipeline | ✅ Full | ❌ | Cloud only |
| Deal-level analytics | ✅ 15+ dims | ❌ | ❌ |
| MQL5 compilation | ✅ | ❌ | ❌ |
| macOS/Linux native | ✅ | Windows only | Cloud |
| Optimization | ✅ Background | ❌ | ✅ Paid |
Quick Install
1. Download & Setup
curl -L -o mt5.tar.gz https://github.com/masdevid/mt5-mcp/releases/latest/download/mt5-quant-macos-arm64.tar.gz
tar -xzf mt5.tar.gz
bash scripts/setup.sh
2. Register MCP Server
Claude Code
# Navigate to your project directory first
cd /path/to/your/mt5-quant
# Register MCP server (requires absolute path)
claude mcp add MT5-Quant -- $(pwd)/mt5-quant
# Verify installation
claude mcp list
Windsurf
Add to ~/.windsurf/config.yaml:
mcpServers:
mt5-quant:
command: /absolute/path/to/mt5-quant
env:
MT5_MCP_HOME: /absolute/path/to/mt5-quant
Or use the config command:
# Get absolute path
which mt5-quant
# Add to Windsurf config
cat >> ~/.windsurf/config.yaml << EOF
mcpServers:
mt5-quant:
command: $(which mt5-quant)
env:
MT5_MCP_HOME: $(dirname $(which mt5-quant))
EOF
Note: MCP servers require absolute paths. Use
$(pwd)or full path like/Users/name/mt5-quant/mt5-quant, not relative paths like./mt5-quant.
Quick Start
Run a backtest on MyEA from 2025.01.01 to 2025.03.31
The AI runs the full pipeline: compile → clean cache → backtest → extract → analyze.
Documentation
| Doc | Purpose |
|---|---|
| QUICKSTART.md | Complete setup for macOS/Linux |
| CONFIG.md | Configuration reference |
| WINDSURF.md | Windsurf IDE integration |
| TOOLS.md | All 57 tools documented |
| ARCHITECTURE.md | Design and internals |
| TROUBLESHOOTING.md | Common issues |
| REMOTE_AGENTS.md | Linux optimization agents |
MCP Tools (57)
Core workflow
| Tool | Description |
|---|---|
run_backtest |
Full pipeline: compile → clean → backtest → extract → analyze |
run_optimization |
Genetic optimization (background, returns immediately) |
get_optimization_results |
Parse optimization results after MT5 finishes |
analyze_report |
Read analysis.json from any report directory |
compare_baseline |
Compare report vs baseline, return winner/loser verdict |
compile_ea |
Compile MQL5 EA via MetaEditor |
list_experts |
List all EAs in MQL5/Experts directory |
list_indicators |
List all indicators in MQL5/Indicators directory |
list_scripts |
List all scripts in MQL5/Scripts directory |
healthcheck |
Quick server health check |
Granular Analytics (individual analysis)
| Tool | Description |
|---|---|
analyze_monthly_pnl |
Monthly P/L breakdown only |
analyze_drawdown_events |
Drawdown events and causes only |
analyze_top_losses |
Worst losing deals only |
analyze_loss_sequences |
Consecutive loss patterns only |
analyze_position_pairs |
Position hold time and P/L pairs |
analyze_direction_bias |
Buy vs Sell performance |
analyze_streaks |
Win/loss streak analysis |
analyze_concurrent_peak |
Peak simultaneous positions |
Use these for targeted analysis, or analyze_report to run all at once.
Monitoring
| Tool | Description |
|---|---|
verify_setup |
Check Wine/MT5 paths, Wine version, and EA/set file counts |
get_backtest_status |
Check live progress of a running backtest pipeline |
get_optimization_status |
Check live state of a background optimization job |
list_jobs |
All optimization jobs with compact status in one call |
Reports & logs
| Tool | Description |
|---|---|
list_reports |
Compact table of all runs with key metrics — no full analysis needed |
get_latest_report |
Get most recent report with optional equity chart |
search_reports |
Find reports by EA, symbol, date range, or profit criteria |
tail_log |
Read last N lines of any log; filter=errors to see only failures |
prune_reports |
Delete old report directories, keep last N (skips _opt dirs) |
History & baseline
| Tool | Description |
|---|---|
archive_report |
Convert one report dir → compact JSON entry in backtest_history.json, optionally delete source |
archive_all_reports |
Bulk-archive all report dirs then optionally delete them; keeps N newest safe |
get_history |
Query history with filters (EA, symbol, verdict, profit, DD) and sort options |
annotate_history |
Attach verdict / notes / tags to any history entry |
promote_to_baseline |
Write a history entry or report to baseline.json for compare_baseline |
Cache management
| Tool | Description |
|---|---|
cache_status |
MT5 tester cache size breakdown by symbol — check before cleaning |
clean_cache |
Delete tester cache files; supports per-symbol and dry_run |
Pre-flight & Validation
| Tool | Description |
|---|---|
get_active_account |
Get current MT5 account session (login, server, available symbols) |
check_symbol_data_status |
Validate symbol has sufficient history data for date range |
check_mt5_status |
Check if MT5 terminal is installed and ready |
validate_ea_syntax |
Pre-compile syntax check without running full compilation |
Project Management
| Tool | Description |
|---|---|
init_project |
Scaffold new MQL5 project with templates (scalper/swing/grid/basic) |
create_set_template |
Generate .set parameter file from EA input variables |
export_report |
Export backtest report to CSV, JSON, or Markdown |
History & Comparison
| Tool | Description |
|---|---|
get_backtest_history |
List all backtests for EA/symbol with summary metrics |
compare_backtests |
Compare 2+ backtest results side-by-side with analysis |
.set file — read / write
| Tool | Description |
|---|---|
list_set_files |
All .set files in tester profiles dir with sweep stats and combination counts |
read_set_file |
Parse UTF-16LE .set file → structured JSON params |
write_set_file |
Write full params dict → UTF-16LE .set with chmod 444 |
patch_set_file |
Update specific params in-place, return diff — replaces read→edit→write |
clone_set_file |
Copy .set to new path with optional overrides in one call |
.set file — analysis & generation
| Tool | Description |
|---|---|
describe_sweep |
Swept params, value counts, and total optimization combinations |
diff_set_files |
Side-by-side diff of two .set files — only changed params returned |
set_from_optimization |
Generate a clean backtest .set from get_optimization_results params; optionally narrow sweep |
Search & Discovery
| Tool | Description |
|---|---|
search_experts |
Search EAs by name pattern across all directories |
search_indicators |
Search indicators by name pattern |
search_scripts |
Search scripts by name pattern |
copy_indicator_to_project |
Copy indicator to project directory |
copy_script_to_project |
Copy script to project directory |
Full schema: docs/MCP_TOOLS.md
Troubleshooting
Run verify_setup from Claude first — it checks all paths and returns actionable hints.
License
MIT
Built from battle-tested production infrastructure. Every edge case in the pipeline was hit in production.