mcp-mt5

Model Context Protocol server for the MetaTrader 4/5 build pipeline. Compile MQL sources, deploy compiled EAs, run Strategy Tester, parse reports, tail logs — all driven by an LLM agent without touching the MetaTrader UI.

Python License: MIT Platform

What this is — and what it isn't

✅ This server	❌ Not this server
MetaTrader dev harness — compile, deploy, backtest, parse	Live trading (orders, positions, quotes)
Wraps `MetaEditor64.exe` / `terminal64.exe` CLI directly	Wraps the `MetaTrader5` Python package
Runs entirely offline against installed terminal	Connects to a broker server
Iterates strategies before they go live	Executes strategies in production

Use case: an LLM agent edits .mq5 source → compiles → deploys → runs Strategy Tester → reads report → adjusts → repeats. No broker login, no human in the loop, no risk of real-money execution.

For runtime trading, pair this with a live-trading MCP — they target different layers and compose well.

Tools

The server exposes 32 tools and 3 MCP resources across nine categories.

🔍 Discovery & terminal selection

Tool	Description
`env_info`	Dump resolved paths, terminal hash, edition, and missing-component issues
`list_terminals`	Enumerate every MT4/5 terminal data folder under `%APPDATA%\MetaQuotes\Terminal` along with each `origin.txt` install path
`select_terminal`	Switch the active terminal data folder mid-session by origin path, hash, or install dir — handy for testing across multiple brokers

🔨 Build & deploy

Tool	Description
`compile`	Invoke MetaEditor CLI on a `.mq4`/`.mq5`/`.mqh` source. Returns structured `errors[]`/`warnings[]` (file, line, column, error code, message) plus log excerpt
`compile_and_deploy`	Compile, then copy the resulting `.ex4`/`.ex5` into the terminal's `Experts/` folder in one call
`syntax_check`	Same as `compile` but uses MetaEditor's `/s` syntax-only mode for faster feedback
`smoke_test`	Compile + deploy + run a 1-day headless backtest + scan the journal for runtime errors. Catches problems that pass `compile` but fail at runtime
`deploy_ea`	Copy a compiled binary into `Experts/` (with optional rename)
`install_include`	Copy a `.mqh` header into the terminal `Include/` folder — handy for libraries like `LiveLog.mqh`
`list_experts`	Enumerate `Experts/` recursively with size and modification time

🔎 Source analysis

Tool	Description
`extract_inputs`	Parse `input <type> <name> = <default>;` declarations into structured records
`gen_tester_inputs`	Auto-build a `[TesterInputs]` block from EA source (translates `PERIOD_*` enums to numeric codes), optionally write into an existing `tester.ini`
`resolve_includes`	Recursive `#include` resolution that reports missing files and circular references
`find_symbol`	Grep a symbol across MQL files, skipping comments and string literals
`code_metrics`	LOC, function count, max nesting per file — or aggregated across an entire tree
`extract_doc`	Pull MetaEditor `//+--+ //\| ... +--+` doc blocks out as markdown
`find_magic_collision`	Detect duplicate magic-number assignments across the project

⚠️ Lint & validation

Tool	Description
`lint_basic`	Structural rules: missing `OnInit`/`OnDeinit`, unused `input`s, hardcoded magic numbers, hardcoded symbol literals
`check_deprecated`	Flag MT4-style API calls (`OrderSend`, `Ask`, `AccountBalance`, …) with `CTrade`/MT5-API replacement suggestions
`validate_tester_ini`	Sanity-check a `tester.ini` (required keys, date format, numeric ranges) and cross-check `[TesterInputs]` against the EA source declarations

🎨 Format

Tool	Description
`format_mql`	Format a source file via `clang-format` (treats MQL as C++ with an MQL-friendly default style)
`format_check`	Same as above but reports whether changes are needed without writing the file

✏️ Refactor

Tool	Description
`rename_symbol`	Whole-word rename across all MQL files in a tree, with `dry_run` preview
`extract_function`	Brace-aware extraction of a contiguous block into a new helper function — inline or into an external `.mqh`

📊 Strategy Tester

Tool	Description
`patch_tester_ini`	Programmatically update keys in a `tester.ini` (e.g. `Tester.Symbol`, `Tester.FromDate`, `TesterInputs.RiskPct`) before running
`run_backtest`	Launch `terminal64.exe /config:tester.ini`, optionally headless (when `ShutdownTerminal=1`), and return the latest tester log path
`parse_optimization`	Best-effort parser for the latest `.opt` (optimization passes) binary file
`top_passes`	Sort optimization passes by a chosen criterion and return the top N
`read_tester_report`	Locate and parse the latest tester HTML report into a structured `summary` (net profit, profit factor, drawdown, trade counts, etc.) plus a sample of trade rows
`compare_reports`	Diff two tester reports key-by-key with absolute and percent deltas
`regression_check`	Verify a candidate report stays within guard thresholds vs a baseline (e.g. "net_profit may not drop more than 5%")
`kill_terminal`	`taskkill` if the terminal hangs

📝 Logs & snapshots

Tool	Description
`tail_log`	Tail the last N lines of either `Files/LiveLog.txt`, the daily `Logs/YYYYMMDD.log`, or the most recent tester log. Optional structured parse into `{ts, source, message}` records
`snapshot_sources`	Freeze a copy of source files into a timestamped folder with a `manifest.json`
`list_snapshots`	Enumerate previously captured snapshots

📡 MCP resources

Live, re-readable URIs that an MCP client can poll instead of calling a tool repeatedly.

URI	Description
`mt5://livelog`	Latest tail of `MQL5/Files/LiveLog.txt`
`mt5://journal`	Today's daily MT5 journal log
`mt5://tester-log`	Most recent Strategy Tester journal

Quick start

Install

pip install mcp-mt5

Requires Windows + an installed MetaTrader 4 or 5 terminal.

Register with an MCP client

Most MCP clients accept a JSON entry under mcpServers. The server inherits its configuration from environment variables:

{
  "mcpServers": {
    "mt5": {
      "command": "mcp-mt5",
      "env": {
        "MT5_INSTALL": "C:\\Program Files\\MetaTrader 5"
      }
    }
  }
}

Refer to your client's documentation for the exact config file location.

Verify the install

Once registered, ask your agent to call env_info:

{
  "edition": "mt5",
  "install": "C:\\Program Files\\MetaTrader 5",
  "terminal_hash": "<32-char-hex-hash>",
  "metaeditor": "C:\\Program Files\\MetaTrader 5\\MetaEditor64.exe",
  "experts_dir": "C:\\Users\\<you>\\AppData\\Roaming\\MetaQuotes\\Terminal\\<hash>\\MQL5\\Experts",
  "issues": []
}

An empty issues array means everything is wired up correctly.

Configuration

Resolution priority for the MetaTrader install + data folder:

Explicit env vars (below)
Auto-scan of %APPDATA%\MetaQuotes\Terminal\*\origin.txt for a folder whose origin matches MT5_INSTALL
Portable mode fallback (data colocated with install dir)

Env var	Default	Notes
`MT5_INSTALL`	`C:\Program Files\MetaTrader 5`	Install dir containing `terminal64.exe`
`MT5_DATA`	(auto-detected)	`%APPDATA%\MetaQuotes\Terminal\<hash>`
`MT5_TERMINAL_HASH`	(auto-detected)	32-char folder name
`MT5_EDITION`	`mt5`	Set to `mt4` for MetaTrader 4

MT4 support

Set MT5_EDITION=mt4 and point MT5_INSTALL at your MT4 install. The server switches to metaeditor.exe (32-bit), terminal.exe, and the MQL4/ data tree automatically.

Example workflow

A typical LLM-driven iteration loop:

1. env_info                                          → verify paths
2. compile_and_deploy source="MyEA.mq5"              → 0 errors, .ex5 deployed ✅
3. patch_tester_ini config="tester.ini" updates={
     "Tester.Symbol": "EURUSD",
     "Tester.FromDate": "2025.01.01",
     "TesterInputs.RiskPct": "1.5"
   }
4. run_backtest config="tester.ini" wait=true
5. read_tester_report                                → summary.net_profit = 1234.56
                                                       summary.profit_factor = 1.45
6. tail_log mode="tester" lines=200 structured=true  → diagnose journal warnings
7. <edit Signal.mqh based on findings>
8. → loop back to step 2

A sample `tester.ini`

; Launch: terminal64.exe /config:tester.ini
; Period codes: M1=1, M5=5, M15=15, H1=16385, H4=16388, D1=16408
; Model: 0=Every tick, 1=1 min OHLC, 4=Real ticks

[Tester]
Expert=MyEA
Symbol=EURUSD
Period=M15
Model=1
FromDate=2024.01.01
ToDate=2024.12.31
Deposit=10000
Currency=USD
Leverage=500
Visual=0
ShutdownTerminal=1     ; required so run_backtest can wait for the run to finish
Report=tester_report

[TesterInputs]
; ParamName=value||start||step||stop||(N=fixed|Y=optimize)
; RiskPct=1.0||0.1||0.1||3.0||N

A more complete sample lives at examples/tester.ini.

Development

git clone https://github.com/PHUICMT/mcp-mt5
cd mcp-mt5
pip install -e ".[dev]"
pytest                    # runs the 18-test suite
ruff check src tests      # lints

CI runs on Windows for Python 3.10, 3.11, and 3.12 against every push to main. Tagging a release (e.g. v0.2.0) triggers an OIDC publish to PyPI.

Project layout

mcp-mt5/
├── src/mcp_mt5/
│   ├── server.py        # FastMCP tool definitions
│   ├── paths.py         # Layout detection + origin.txt scan
│   └── parsers.py       # Compile log + tester HTML report parsers
├── tests/               # 18 pytest tests, no live MT5 required
├── examples/            # Sample tester.ini + client config
└── .github/workflows/   # CI + PyPI release

Limitations

Windows-only. MetaTrader CLI binaries don't ship for Linux/macOS. Wine ports may work but are untested.
No live broker access. This server intentionally never authenticates to a broker. Use a separate MCP server for runtime trading.
Tester report parsing is best-effort. MetaTrader's HTML output isn't a stable schema; the raw HTML is also returned alongside the parsed structure so you can fall back to text inspection when needed.
Optimization runs are not parsed yet. Single-pass backtests are fully supported; .opt results are on the roadmap.

Roadmap

All v0.3.x roadmap items shipped in v0.4.0. Future ideas:

Real tree-sitter MQL grammar for extract_function (current implementation is brace-counting + regex)
WebSocket transport for long-lived sessions (currently stdio only)
Linux/Wine port for non-Windows agents

mcp-mt5

mcp-mt5

What this is — and what it isn't

Tools

🔍 Discovery & terminal selection

🔨 Build & deploy

🔎 Source analysis

⚠️ Lint & validation

🎨 Format

✏️ Refactor

📊 Strategy Tester

📝 Logs & snapshots

📡 MCP resources

Quick start

Install

Register with an MCP client

Verify the install

Configuration

MT4 support

Example workflow

A sample `tester.ini`

Development

Project layout

Limitations

Roadmap

License

Latest Blog Posts

MCP directory API

mcp-mt5

What this is — and what it isn't

Tools

🔍 Discovery & terminal selection

🔨 Build & deploy

🔎 Source analysis

⚠️ Lint & validation

🎨 Format

✏️ Refactor

📊 Strategy Tester

📝 Logs & snapshots

📡 MCP resources

Quick start

Install

Register with an MCP client

Verify the install

Configuration

MT4 support

Example workflow

A sample tester.ini

Development

Project layout

Limitations

Roadmap

License

Latest Blog Posts

MCP directory API

A sample `tester.ini`