MT5-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
Full Setup →
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
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.
Full Troubleshooting Guide →
License
MIT
Built from battle-tested production infrastructure. Every edge case in the pipeline was hit in production.