mt5-quant

# MT5-Quant

[![OpenSSF Scorecard](https://api.scorecard.dev/projects/github.com/masdevid/mt5-quant/badge)](https://scorecard.dev/viewer/?uri=github.com/masdevid/mt5-quant) [![CII Best Practices](https://bestpractices.coreinfrastructure.org/projects/<CII_PROJECT_ID>/badge)](https://bestpractices.coreinfrastructure.org/projects/<CII_PROJECT_ID>) <!-- TODO: replace <CII_PROJECT_ID> with your project number from bestpractices.coreinfrastructure.org after enrolling; badge activates then --> [![Rust CI](https://github.com/masdevid/mt5-quant/actions/workflows/rust.yml/badge.svg)](https://github.com/masdevid/mt5-quant/actions/workflows/rust.yml) [![crates.io](https://img.shields.io/crates/v/mt5-quant.svg)](https://crates.io/crates/mt5-quant) [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)

**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](https://pypi.org/project/MetaTrader5/), 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)

```bash
cargo install mt5-quant --locked
```

#### Option B — Pre-built binaries (no toolchain)

```bash
# 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**

```bash
claude mcp add mt5-quant -- mt5-quant --stdio
```

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

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

**Cursor** — `.cursor/mcp.json` (same JSON shape as Claude Desktop)

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

**opencode** — `.opencode/opencode.jsonc`

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

**Codex CLI** — `~/.codex/config.toml`

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

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

```bash
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 |
|