MT5-MCP: Strategy Testing for Every LLM

This is a Model Context Protocol (MCP) server for MetaTrader 5 strategy testing. It lets any LLM (Claude, GPT-4, Ollama, etc.) compile Expert Advisors, run backtests with arbitrary settings, and receive structured results — all via MCP tools.

This repo is a fork of Qoyyuum/mcp-metatrader5-server extended with corrected strategy-tester workflows, terminal.ini date-range editing (the original approach doesn't work), and automatic HTML/CSV report generation.

TL;DR — For an AI Setting This Up for the First Time

1. Ask the user for their MetaTrader 5 installation path and data folder path

2. Copy configs/env.example → .env at repo root, fill in the paths

3. uv sync (or pip install -e .)

4. Register the MCP server in your claude_desktop_config.json, cursor_config.json, etc.

5. Call run_strategy_tester() — done

Related MCP server: MetaTrader MCP Server

Prerequisites

💡 If you only have a .mq5 file and no MT5 installed: You need MT5 (with MetaEditor) to compile and test. There is no cloud alternative that produces real strategy-tester results.

Installation (Step-by-Step for AI Agents)

Step 1: Discover the user's MT5 paths

Ask the user:

"Where is your MetaTrader 5 installed? Please provide the full path to terminal64.exe."

"Can you open MetaTrader 5 and go to File → Open Data Folder? Please paste the folder path shown in the address bar."

Typical paths:

If you can't get the data folder path from the user, find it programmatically:

import glob, os
candidates = glob.glob(r"C:\Users\*\AppData\Roaming\MetaQuotes\Terminal\*\")
# Look for folders containing MQL5/ and Config/

Step 2: Configure environment

cp configs/env.example .env

Edit .env and set:

• MT5_PATH → path to terminal64.exe

• MT5_METAEDITOR_PATH → path to MetaEditor64.exe

• MT5_DATA_FOLDER → the data folder path from "Open Data Folder"

• MT5_CONFIG_FOLDER → [data_folder]\Config

• MT5_TESTER_LOG → [data_folder]\Tester\logs

• MT5_TERMINAL_INI → [data_folder]\terminal.ini

Step 3: Install dependencies

uv sync        # recommended
# OR
pip install -e ".[dev]"

Step 4: Register as MCP server

Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "mt5": {
      "command": "uv",
      "args": ["run", "mt5mcp"],
      "cwd": "C:\\path\\to\\this\\repo"
    }
  }
}

Cursor (~/.cursor/mcp.json):

{
  "mcpServers": {
    "mt5": {
      "command": "uv",
      "args": ["run", "mt5mcp"],
      "cwd": "C:\\path\\to\\this\\repo"
    }
  }
}

Windsurf (.openhands.json):

{
  "mcpServers": {
    "mt5": {
      "command": "uv",
      "args": ["run", "mt5mcp"],
      "cwd": "C:\\path\\to\\this\\repo"
    }
  }
}

Step 5: Verify

Restart your LLM client, then ask it:

"List available MCP tools and specifically the MT5 tools"

You should see tools like: compile_mql5, run_strategy_tester, read_test_report, list_strategies, get_account_info, order_send, etc.

MCP Server Tools (Extended)

The original Qoyyuum server provides 50+ tools for trading (order_send, positions_get, history_deals_get, etc.). This fork adds/fixes:

run_strategy_tester — Corrected Workflow

from mcp_mt5.main import run_strategy_tester

result = run_strategy_tester(
    ea_name="Moving Average.ex5",       # NO "Experts\" prefix!
    symbol="EURUSD",
    period="H1",
    model=0,                            # 0 = every tick (only reliable mode)
    deposit=10000,
    from_date="2026.09.14",             # YYYY.MM.DD
    to_date="2026.09.16",
    timeout=600,
)
print(result["metrics"])

read_test_report — Dual-Mode Parser

from mcp_mt5.main import read_test_report

# From HTML report (if generated)
result = read_test_report(r"C:\...\TestReport.html")

# From Tester log (UTF-16-LE, fallback when no HTML)
result = read_test_report(r"C:\...\Tester\logs\20260918.log")

Standalone Scripts

The scripts/ folder contains standalone Python scripts that work without the MCP server:

run_backtest.py — One-shot pipeline

python scripts/run_backtest.py \
    --ea "Moving Average.ex5" \
    --symbol EURUSD \
    --period H1 \
    --from-date 2026.09.14 \
    --to-date 2026.09.16 \
    --save-html outputs/html_reports/ \
    --save-excel outputs/excel_reports/

This will:

1. Modify terminal.ini for the date range

2. Write a tester config file

3. Launch MT5, run the test

4. Parse the Tester log

5. Save HTML + CSV reports

compile_ea.py — Compile only

python scripts/compile_ea.py "Experts\MyExpert.mq5"

test_quick.py — Quick smoke test

python scripts/test_quick.py

Tests the Moving Average example EA on EURUSD/H1 for 3 days and saves reports to outputs/.

⚠️ Critical Workflow Knowledge

These are hard-won insights from extensive testing. Skip at your peril:

1. Date ranges MUST be set in terminal.ini, NOT the config file

MT5's config .ini file parameters TestDateMode, TestFromDate, and TestToDate are completely ignored by the terminal. The only way to set a date range is to directly edit terminal.ini's [Tester] section:

DateFrom=1789344000   (Unix timestamp for 2026-09-14)
DateTo=1789516800     (Unix timestamp for 2026-09-16)

The patched _modify_terminal_ini() function handles this automatically, including:

• UTF-16-LE encoding preservation

• BOM (Byte Order Mark) detection and re-insertion

• Only touching values in the [Tester] section

2. Config file must NOT have a [Common] section

Adding [Common] Enable=1 to the config file prevents the strategy tester from triggering. The test will not start ("Tester automatic testing started" never appears in logs).

3. Model=0 (every tick) is the only reliable testing model

4. EA filename must NOT include Experts\ prefix

MT5 automatically prepends Experts\ to the EA path. Including it manually causes Experts\Experts\EA.ex5 — double prefix error.

✅ Correct: Expert=Moving Average.ex5
✅ Correct: Expert=Examples\Moving Average\Moving Average.ex5
❌ Wrong: Expert=Experts\Moving Average.ex5

5. Period uses STRING in config, NUMERIC in terminal.ini

• Config file: Period=H1 (string)

• terminal.ini: Period=16397 (numeric MT5 enum)

The patched _period_to_mt5_enum() converts automatically.

6. Historical data must be pre-cached

The first strategy test for a symbol downloads historical M1 data, which takes ~67 seconds for EURUSD. To avoid this:

1. Run a quick test first to trigger data download

2. Or use the MT5 Python API to pre-cache:

import MetaTrader5 as mt5
mt5.initialize(path="C:\\...\\terminal64.exe")
mt5.copy_rates_from("EURUSD", mt5.TIMEFRAME_M1, datetime(2020,1,1), 50000)

7. Tester logs are UTF-16-LE encoded

MT5 stores logs as UTF-16-LE. Use _read_utf16_log() to read them — cat or the filesystem read_file tool will show garbage.

8. HTML report is not always generated

When terminal is killed too quickly after test completion, the HTML report (TestReport.html) is not written. The patched code falls back to parsing the Tester log to extract metrics, and generates a fallback HTML report from log data.

9. AutoTrading must be ENABLED for EA execution

Check common.ini in the Config folder:

[Common]
Enable=1

If AutoTrading is disabled, EAs won't execute during testing.

File Structure

mt5-mcp/
├── README.md                          # This file
├── pyproject.toml                     # Python package config (from Qoyyuum)
├── .env.example                       # Environment template
├── .gitignore
├── LICENSE
├── src/
│   └── mcp_mt5/
│       ├── __init__.py                # MCP server entry point
│       └── main.py                    # Patched: 54 tools incl. corrected tester
├── scripts/
│   ├── run_backtest.py                # Standalone: compile + test + report
│   ├── compile_ea.py                  # Standalone: just compile .mq5 → .ex5
│   ├── test_quick.py                  # Quick smoke test (Moving Average EA)
│   ├── helpers.py                     # Helper functions (spliced into main.py)
│   ├── new_run_strategy_tester.py     # Replacement function (for patching)
│   ├── new_read_test_report.py        # Replacement function (for patching)
│   └── patch_main_v2.py              # Script that patches main.py
├── configs/
│   ├── env.example                    # .env template with instructions
│   └── tester_config_example.ini      # Strategy tester config template
└── outputs/
    ├── html_reports/                  # HTML report output
    └── excel_reports/                 # CSV report output

Quick Start

# 1. Clone
git clone https://github.com/Roan2802/MT5-MCP.git
cd MT5-MCP

# 2. Configure
cp configs/env.example .env
# Edit .env with your MT5 paths

# 3. Install
uv sync

# 4. Quick test (Moving Average EA, EURUSD H1, 3-day range)
python scripts/test_quick.py

# 5. Custom test
python scripts/run_backtest.py \
    --ea "Advisors\\MyStrategy.ex5" \
    --symbol XAUUSD \
    --period H1 \
    --from-date 2024.01.01 \
    --to-date 2024.01.07 \
    --deposit 5000

# 6. Compile an EA
python scripts/compile_ea.py "Experts\\MyExpert.mq5"

License

MIT — forks the Qoyyuum/mcp-metatrader5-server MIT license and extends it.