MT5-Quant MCP server

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.

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

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)

cargo install mt5-quant --locked

Option B — Pre-built binaries (no toolchain)

# 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

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 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 (same JSON shape as 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"]

Then finish setup (auto-detects Wine + MT5 paths):

bash scripts/setup.sh

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.sh to auto-detect Wine and MT5 paths, and register it as an MCP server."

First Backtest

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.

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 health
• search_mt5_errors — Find crash causes in logs
• check_mt5_process + kill_mt5_process — Detect and kill stuck processes
• get_backtest_crash_info — Investigate failed backtest reports

Full Troubleshooting Guide →

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

---