**The MCP server for MT5 strategy development — not live trading.**
Most MT5 MCP servers let an AI place orders. MT5-Quant lets an AI *build the strategy*: compile an Expert Advisor, run a backtest, parse the report, analyze every deal, and optimize parameters — all in one conversation, on **macOS or Linux**, without a Windows machine.
```
You: "Run a backtest from Jan to March and tell me what caused the drawdown spike in February"
MT5 runs under Wine on both macOS and Linux. Two supported paths:
**macOS — MetaTrader 5.app (recommended, free)**
Download from [metatrader5.com](https://www.metatrader5.com/en/download) and install to `/Applications`. Launch it once so it initializes the Wine prefix (~30 s), then quit.
Every backtest produces `analysis.json` — a stable, AI-readable artifact.
The analysis engine is **strategy-agnostic**: a `PROFILES` system drives keyword matching, depth extraction, and cycle grouping so the same pipeline works for any EA type.
| `direction_bias` | Buy vs sell win rate and P/L | — |
| `streak_analysis` | Max win/loss streaks, current streak | — |
| `session_breakdown` | Asian / London / London-NY / New York P/L | — |
| `weekday_pnl` | Mon–Sun P/L and win rate | — |
| `concurrent_peak` | Peak simultaneous open positions | — |
| `hourly_pnl` | Hour 0–23 (`--deep` only) | — |
| `volume_profile` | P/L by lot tier (`--deep` only) | — |
This is what makes AI reasoning over backtest results possible — across any EA type.
Full architecture: [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md)
---
## Backtest History
Every experiment can be archived into a single JSON ledger at `config/backtest_history.json` — a permanent, queryable record of every run. This lets you delete raw report directories (which can be GBs of tick data) while keeping all results as compact JSON.
```
[workflow]
run_backtest → archive_report(delete_after=true) # disk reclaimed
↓
backtest_history.json (grows forever, tiny)
↓
get_history(min_profit=5000, max_dd_pct=15) # query past runs
↓
promote_to_baseline # set new production reference
```
**Files** (both gitignored, live in `config/`):
| File | Purpose |
|------|---------|
| `config/backtest_history.json` | Ledger of all archived backtest runs with full metrics, analysis summary, monthly P/L, and verdict |
| `config/baseline.json` | Current production reference — used by `compare_baseline` and the Claude Code hook |
Each history entry captures: all `metrics.json` fields + `analysis.json` summary + monthly P/L array + worst DD event. The raw report directory can be safely deleted after archiving.
`--claude-code` generates two files that make Claude aware of your trading context:
```bash
bash scripts/setup.sh --claude-code
```
| File | Purpose |
|------|---------|
| `config/CLAUDE.template.md` | Copy to your EA project root as `CLAUDE.md`. Encodes MT5-Quant rules, baseline tracking policy, and symbol name reminders. |
| `.claude/hooks/user-prompt-submit.sh` | Runs before every Claude prompt. Reads `config/baseline.json` and injects your production metrics as context. |
Update this file whenever a new version is promoted to production — either by running `promote_to_baseline` from Claude, or by editing it manually. Every subsequent Claude prompt will automatically include these metrics so Claude can tell you whether a new backtest is actually an improvement without you having to paste the numbers.
**Why this matters:** Without the baseline hook, you have to manually remind Claude what the production numbers are at the start of every session. With it, that context is always present.
---
## Troubleshooting
Run `verify_setup` from Claude first — it checks all paths and returns actionable hints.
### Wine not found
**macOS:** Confirm `/Applications/MetaTrader 5.app` exists and has been launched at least once. If using CrossOver, confirm the bottle is named correctly.
```bash
# Check what setup.sh found:
bash scripts/platform_detect.sh
```
**Linux:**
```bash
sudo apt install wine64 # Debian/Ubuntu
sudo dnf install wine # Fedora/RHEL
which wine64 # confirm it's on PATH
```
### terminal64.exe missing
MT5 unpacks `terminal64.exe` only after its first launch. Open MetaTrader 5.app, wait for initialization (~30 s), then quit. Re-run setup:
```bash
bash scripts/setup.sh --yes
```
### MCP server not appearing in Claude
```bash
claude mcp list # should show MT5-Quant
claude mcp remove MT5-Quant # remove stale entry if needed
Use an **absolute path** — relative paths break when Claude starts from a different working directory.
### Report not found after backtest
1.**Wrong symbol name** — brokers use custom names (`XAUUSDm`, `XAUUSD.cent`). Check `verify_setup` → `experts_dir`, or look in `<terminal_dir>/history/` for available symbols.
2.**No history data** — open MT5, open the symbol's chart, wait for history to download, then retry.
3.**EA crash at startup** — check `<terminal_dir>/MQL5/Logs/` for `OnInit` errors.
4.**Date range has no trades** — try a wider range or confirm the symbol was active during that period.
### MetaEditor compile errors
Log at `<terminal_dir>/MQL5/Logs/`. Common causes:
- Missing `#include` files — copy dependencies into `Experts/` alongside the `.mq5`
- Stale `.ex5` from a different MT5 build — delete it and recompile
### No deals in backtest report
- Use `model=0` (every tick) — models 1 and 2 skip intra-bar movement, producing zero deals for grid/martingale EAs
- Check the `.set` file has values appropriate for the symbol/broker
