mt5

MetaTrader 5 CLI for headless Linux. Compile, backtest, run, monitor, and serve a REST/WebSocket API — zero npm dependencies (Bun built-ins only).

Two runtimes:

• Docker (default) — MT5 runs in a Wine container (image mt5-exness).
• Native — MT5 runs directly on the host via Wine (--runtime native).

Install

# requires Bun: https://bun.sh
bun install -g mt5cli

Quick start

mt5 init default
mt5 config set MT5_LOGIN 12345
mt5 config set MT5_PASSWORD '***'
mt5 config set MT5_SERVER Exness-MT5Trial6
mt5 doctor

Profiles live at ~/.mt5/profiles/<name>.env. Use --profile <name> with any command to select another profile.

Commands

# Compile a normal EA.
mt5 compile ./MyEA.mq5

# EA with #resource "\\Files\\model.onnx" or other embedded assets.
# --files mounts this directory at MQL5/Files for MetaEditor.
mt5 compile ./MyEA.mq5 --files ./MQL5/Files

# Backtest. Report artifacts (html/xml/media) land in --out (default ./mt5-reports).
# HTML is converted to Markdown by default; pass --raw-report to keep it.
# --screenshot captures the tester window during the run (docker only).
# --pdf converts the html report to PDF (needs chromium/wkhtmltopdf/libreoffice).
mt5 backtest ./MyEA.ex5 --symbol BTCUSDm --period M1 \
  --from 2026.08.13 --to 2026.08.14 --deposit 100000 \
  --set ./MyEA.set

# Forward/live run. Trading stays off unless --allow-live-trading is explicit.
mt5 run ./MyEA.ex5 --symbol BTCUSDm --period M1 \
  --name myea --set ./MyEA.set --allow-live-trading

# Monitor a run.
mt5 list
mt5 status myea
mt5 logs myea --tail 50
mt5 stop myea                     # does NOT close positions by default
mt5 stop myea --close-positions   # opt-in (needs MT5_API_URL + run manifest)
mt5 version                       # print CLI version string

Dashboard UI

A dark-theme single-page overview at /dashboard — auto-refresh every 5s, no framework needed. Displays account count, online status, error count, and per-account cards with balance, equity, profit, position value, deal count (24h), and health dot.

| Endpoint | Description | |---|---| | GET /dashboard | Read-only HTML dashboard (no auth required) | | GET /api/v1/dashboard?full=1 | JSON aggregate data: account status, balance, equity, positions, error counts |

Data / info (read-only)

These use the REST API (MT5_API_URL), or mt5 serve you run yourself.

mt5 account
mt5 symbol BTCUSDm
mt5 terminal
mt5 positions
mt5 rates BTCUSDm --tf H1 --count 100
mt5 ticks BTCUSDm
mt5 export BTCUSDm --tf M1 --from 2026.08.01 --to 2026.08.02 --csv out.csv

Serve an API server

mt5 serve runs the Bun gateway + a Python MT5 worker (the official MetaTrader5 package, numpy). FastAPI/uvicorn are not required.

# Native (default): gateway + worker on the host. Needs python3 + MetaTrader5
# lib + an installed terminal (MT5_TERMINAL_PATH in the profile).
mt5 serve --port 8000

# Docker: one container with the gateway + worker + terminal bundled.
mt5 serve --runtime docker

# Multi-account: one gateway, N workers, route via the X-Account header.
mt5 serve --accounts exness,metaquotes

| Endpoint | Description | |---|---| | GET /health, GET / | health / service info (account list) | | GET /openapi.json, GET /docs | OpenAPI spec + Swagger UI | | GET /api/v1/terminal / /account / /symbols / /symbols/{sym} | info | | GET /api/v1/rates/{sym} / /ticks/{sym} / /indicators/{sym} / /gold | market data | | POST /api/v1/orders, GET /api/v1/orders, PUT|DELETE /api/v1/orders/{ticket} | orders | | GET /api/v1/positions, POST /api/v1/positions/{ticket}/close, POST /api/v1/positions/{ticket}/modify | positions (modify = SL/TP) | | GET /api/v1/history/deals / /history/orders | history | | POST /api/v1/reconnect | reconnect terminal (drops & re-establishes) | | WS /ws?symbol=BTCUSDm&kind=ticks|rates | realtime stream (1s push) |

Auth: set MT5_API_KEY; then every /api/v1/* + /ws requires the X-API-Key header. Route multi-account requests with the X-Account header.

Dynamic accounts (admin)

Set MT5_ADMIN_KEY to enable account CRUD. Static accounts (from --accounts) are read-only; dynamic ones live in ~/.mt5/profiles/<name>.env (chmod 600) and spawn a worker on creation.

| Endpoint | Description | |---|---| | GET /api/v1/accounts | list ({name, static}), admin or server key | | POST /api/v1/accounts | add {name, login, password, server, api_key?} → 201 + key | | PUT /api/v1/accounts/{name} | update creds / rotate api_key | | DELETE /api/v1/accounts/{name} | stop worker, delete profile file |

Admin key: full CRUD. Server key: list only. Per-account key (returned once on create): scoped to that account, X-Account ignored. Cap MT5_MAX_ACCOUNTS (default 8). Docker runtime not supported yet.

Configuration

# Runtime
MT5_RUNTIME=docker              # docker | native
MT5_IMAGE=ghcr.io/thodinh/mt5-exness:b6122

# Broker
MT5_LOGIN=
MT5_PASSWORD=
MT5_SERVER=
MT5_DEFAULT_SYMBOL=BTCUSDm
# MT5 terminal executable path (auto-detected; override if needed)
MT5_PATH=
# Custom gold symbol name (default: XAUUSDm). Sets GOLD_SYMBOL env var for indicators endpoint.
MT5_GOLD_SYMBOL=

# Admin API key (enables dynamic account CRUD via /api/v1/accounts endpoints)
MT5_ADMIN_KEY=

# Directory where MT5 is installed (auto-detected; override for non-standard Wine prefixes)
MT5_DIR=

# Data dir (persists broker history between local runs)
MT5_DATA_DIR=~/.mt5-data

# REST API (data/info + serve)
MT5_API_URL=http://127.0.0.1:8000
MT5_API_KEY=
MT5_API_IMAGE=ghcr.io/thodinh/mt5-api:latest   # serve --runtime docker
MT5_PYTHON=python3                              # serve native worker
MT5_API_DIR=                                    # optional path to api/worker.py
MT5_MAX_ACCOUNTS=8                              # cap for --accounts

# Native runtime (Wine on host, MT5 already installed)
MT5_TERMINAL_PATH=            # /path/to/terminal64.exe
MT5_WINE=                     # path to Wine binary directory (wine >= 10)
MT5_WINE_PREFIX=~/.mt5-native/wineprefix

Use the broker's exact symbol name — Exness-MT5Trial6 uses EURUSDm, not EURUSD.

Requirements

• Docker runtime: Docker daemon + the MT5 Wine image. compile needs only the image; backtest/run need MT5 credentials.
• Native runtime: Wine >= 10 + Xvfb + fluxbox on the host, and MT5 installed with MT5_TERMINAL_PATH set.
• mt5 serve native: python3 + MetaTrader5 package (python3 -m pip install MetaTrader5 numpy).
• MQL5/Files assets are supplied at compile time with --files; compiled .ex5 files embed #resource assets, so backtest/run need only the .ex5.

Safety

• Live trading is off by default; use --allow-live-trading to enable it.
• mt5 stop stops the terminal but does not close positions unless --close-positions is passed.
• Data/info commands are read-only.
• Compilation exits non-zero on errors; warnings do not block a usable .ex5.

License

MIT