MT5 Quant README
The full upstream README, mirrored here for reference. Install config, tool schemas, adoption signals, and an original overview live on the MT5 Quant listing page.
MT5-Quant
MCP server for MT5 strategy development on macOS/Linux. 89 tools to compile, backtest, analyze, optimize, debug crashes, and manage MQL5 Expert Advisors — no Windows required.
Why MT5-Quant
Focus: Backtest organization, reporting, and analytics — capabilities MT5 itself doesn't provide.
| MT5-Quant | Others | |
|---|---|---|
| Platform | macOS/Linux native | Windows only |
| Backtest pipeline | ✅ Full (compile → run → analyze) | ✅ Via MT5 Python package |
| Deal-level analytics | ✅ 19 dimensions, DB-backed | ❌ |
| Report organization | ✅ SQLite (reports + deals) + search + history | ❌ |
| MQL5 compilation | ✅ Headless (MetaEditor via Wine, no GUI) | ⚠️ Via GUI or terminal |
| Optimization | ✅ Background + results parsing + .set generation | ⚠️ Terminal only, no parsing |
| Crash debugging | ✅ Wine/MT5 diagnostics | ❌ |
Others typically run on Windows using the MetaTrader5 Python package, providing full terminal operations. MT5-Quant fills the gap: organizing backtest reports, extracting deal-level insights, and managing optimization workflows — none of which MT5 or its Python API expose natively.
Quick Start
Install MT5-Quant
Option A — Cargo (recommended, needs Rust toolchain)
Option B — Pre-built binaries (no toolchain)
Move the binary somewhere on your PATH (e.g. /usr/local/bin or ~/.local/bin) so clients can launch it as mt5-quant.
Option C — Register with your LLM client (copy-paste)
Claude Code
Claude Desktop — ~/Library/Application Support/Claude/claude_desktop_config.json
Cursor — .cursor/mcp.json (same JSON shape as Claude Desktop)
opencode — .opencode/opencode.jsonc
Codex CLI — ~/.codex/config.toml
Then finish setup (auto-detects Wine + MT5 paths):
Tip: you can also just ask your LLM coding agent to do all of the above: "Please install mt5-quant from https://github.com/masdevid/mt5-quant — download or build it, run its
scripts/setup.shto auto-detect Wine and MT5 paths, and register it as an MCP server."
First Backtest
The AI runs the full pipeline: compile → clean cache → backtest → extract → analyze.
MCP Tools (89)
Core workflow
| Tool | Description |
|---|---|
run_backtest | Full pipeline: compile → clean → backtest → extract → analyze |
run_backtest_quick | Quick backtest using pre-compiled EA (skip compile) |
run_backtest_only | Backtest only - just extract raw trades, no analysis |
launch_backtest | Fire-and-forget: launch MT5 backtest, poll for completion |
get_backtest_status | Poll running backtest status (MT5 running, report found, elapsed time) |
run_optimization | Genetic optimization (background, returns immediately) |
get_optimization_results | Parse optimization results after MT5 finishes |
list_jobs | List all optimization jobs with status |
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 |
list_symbols | List all available symbols in MT5 terminal |
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.
Deal-Level Analytics (New)
| Tool | Description |
|---|---|
list_deals | List individual deals with filters (type, profit range, volume, dates) |
search_deals_by_comment | Full-text search in deal comments (e.g., "Layer #3") |
search_deals_by_magic | Filter deals by EA magic number |
analyze_profit_distribution | Profit histogram: small/medium/large wins and losses |
analyze_time_performance | Performance by hour of day and day of week |
analyze_hold_time_distribution | Hold time buckets + correlation with profit |
analyze_layer_performance | Grid/martingale layer analysis from comments |
analyze_volume_vs_profit | Volume correlation + performance by lot size |
analyze_costs | Commission and swap impact on profitability |
analyze_efficiency | Profit per hour/day, annualized return, trade frequency |
Monitoring
| Tool | Description |
|---|---|
verify_setup | Check Wine/MT5 paths, Wine version, and EA/set file counts |
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 |
get_report_by_id | Get specific report by ID with equity chart |
get_reports_summary | Aggregate stats: counts, averages, pass rates |
get_best_reports | Top N reports sorted by any metric (profit factor, drawdown, etc.) |
search_reports_by_tags | Find reports by tags |
search_reports_by_date_range | Query by backtest date range |
search_reports_by_notes | Full-text search in report notes |
get_reports_by_set_file | Find all reports using a specific .set file |
get_comparable_reports | Find comparable reports (same EA/symbol/timeframe) |
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) |
promote_to_baseline | Write a history entry or report to baseline.json for compare_baseline |
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 |
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 |
Debugging & Diagnostics (New)
| Tool | Description |
|---|---|
diagnose_wine | Check Wine installation, version, and prefix health |
get_mt5_logs | Get MT5 terminal, tester, or MetaEditor logs with filtering |
search_mt5_errors | Search logs for error patterns (crash, exception, access violation) |
check_mt5_process | Check if MT5 processes are running, get PID, CPU, memory usage |
kill_mt5_process | Kill stuck MT5 processes (force=true for wineserver) |
check_system_resources | Check disk space, memory, CPU availability |
validate_mt5_config | Validate terminal.ini and tester configuration files |
get_wine_prefix_info | Get Wine prefix details: Windows version, installed programs, registry |
get_backtest_crash_info | Investigate backtest failures: incomplete markers, missing deals.csv, errors |
check_update | Check if a newer version of MT5-Quant is available |
update | Update MT5-Quant to latest release |
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 your LLM first — it checks all paths and returns actionable hints.
For crashes or unexplained failures during backtest/compile/optimization:
diagnose_wine— Check Wine installation and prefix healthsearch_mt5_errors— Find crash causes in logscheck_mt5_process+kill_mt5_process— Detect and kill stuck processesget_backtest_crash_info— Investigate failed backtest reports
Documentation
| Doc | Description |
|---|---|
| QUICKSTART | Step-by-step install, setup, and first backtest |
| MCP_TOOLS | Full input/output schemas for all 90 tools |
| CONFIG | Configuration reference (config/mt5-quant.yaml) |
| ARCHITECTURE | Design principles and internal module layout |
| REMOTE_AGENTS | Distribute optimization across Linux agents via Wine |
| TROUBLESHOOTING | Platform-specific fixes for Wine, MT5, and backtests |
Full index with reading order: docs/INDEX.md
Acknowledgements
MT5-Quant stands on the shoulders of exceptional open-source projects:
- Rust — The language that makes zero-cost abstractions, memory safety, and fearless concurrency practical
- Tokio — The async runtime powering all concurrent operations
- Wine — Making MT5 execution possible on macOS and Linux without Windows licensing
- MetaTrader 5 — MetaQuotes' trading platform (trademark of MetaQuotes Software Corp.)
- rusqlite — Ergonomic SQLite bindings for Rust
- serde — The serialization framework making config and report handling painless
- scraper — HTML parsing for MT5 report extraction
- tempfile — Secure temporary file handling
Special thanks to the Model Context Protocol (MCP) team at Anthropic for defining the standard that makes AI-powered development workflows possible.
Disclaimer
Not Financial Advice. MT5-Quant is a development and analysis tool for algorithmic trading strategies. It does not provide investment advice, trading recommendations, or guarantee profitability. All backtest results are historical simulations and do not guarantee future performance.
Use at Your Own Risk. Trading financial instruments carries substantial risk of loss. The authors and contributors of MT5-Quant accept no liability for:
- Trading losses incurred using strategies developed or tested with this tool
- Data loss or corruption from backtest operations
- Bugs, errors, or incorrect analysis results
- System crashes, Wine compatibility issues, or MT5 failures
Software Warranty. This software is provided "as-is" without warranty of any kind, express or implied, including but not limited to warranties of merchantability, fitness for a particular purpose, or non-infringement. See LICENSE for full terms.
Third-Party Software. MT5-Quant interacts with MetaTrader 5, Wine, and other third-party software. Users are responsible for complying with all applicable licenses and terms of service for these dependencies. MetaTrader is a trademark of MetaQuotes Software Corp. MT5-Quant is not affiliated with, endorsed by, or sponsored by MetaQuotes.
Regulatory Compliance. Users are responsible for ensuring their trading activities comply with applicable financial regulations in their jurisdiction. Automated trading may be restricted or require licensing in some regions.
License
MIT