mtdata

mtdata is a Windows-first research and automation toolkit for MetaTrader 5 (MT5). It turns a running MT5 terminal into repeatable CLI commands, MCP tools, and a local Web API for market data, forecasting, regime detection, signal processing, risk analysis, and reporting.

Use it to explore ideas, build repeatable research workflows, and integrate MT5 data with assistants or local applications. It is a toolkit, not a trading strategy or financial advice.

Who Is This For?

• Newer traders / learners: Follow guided workflows (no quant background required).

• Systematic traders: Prototype ideas, backtest quickly, and automate via CLI/MCP.

• Data folks: Pull MT5 market data into repeatable analysis pipelines.

Related MCP server: OKX MCP Server

Platform Support (Important)

• Windows is required to run MetaTrader 5 (and therefore to run mtdata against MT5).

• If you're on macOS/Linux, run mtdata on a Windows VM or Windows machine and connect remotely (MCP/Web API).

• Python 3.14 is the supported runtime for the packaged dependency set in this repo.

Safety First

• mtdata includes trade_* commands that can place/modify/close real orders on the account currently logged into MT5.

• Use a demo account until you understand the tools and your broker setup.

• There is no built-in “paper trading” mode in mtdata; use an MT5 demo account for simulated execution.

• When a trading command supports --dry-run true, preview the action before sending anything to MT5.

• If you only want research, stick to data_*, forecast_*, regime_*, patterns_*, and report_* commands.

Capabilities

Notes:

• market_depth_fetch is enabled only when MTDATA_ENABLE_MARKET_DEPTH_FETCH=1 and your broker provides Level 2/DOM data.

• Options-chain tools depend on Yahoo Finance endpoint availability. The pure QuantLib calculator options_barrier_price works independently of external options-chain data.

Quick Start

Prerequisites: Windows + Python 3.14 + MetaTrader 5 installed and running (demo account recommended). For the full install on Windows, also install Visual Studio Build Tools 2022 with the Desktop development with C++ workload.

# Optional but recommended: create an isolated conda environment first
conda create -n mtdata python=3.14 -y
conda activate mtdata

# Lean core install
pip install -e .

# Full stable research/web install
pip install -r requirements.txt

# Verify MT5 connection (lists symbols from the running terminal)
mtdata-cli symbols_list --limit 5

# Scan the current MT5 watchlist for top markets
mtdata-cli symbols_top_markets --rank-by all --limit 5 --timeframe H1

# Fetch recent candles
mtdata-cli data_fetch_candles EURUSD --timeframe H1 --limit 50

# Generate a baseline price forecast
mtdata-cli forecast_generate EURUSD --timeframe H1 --horizon 12 --method theta

After these commands work, move through the docs in the learning path below. Keep the first session read-only unless you are using a demo account and intentionally testing trading commands.

Notes:

• pip install -e . now installs the lean core package only.

• pip install -r requirements.txt installs the validated Python 3.14 stack from package-index releases, including Chronos, StatsForecast, sktime, mlforecast, news embeddings, and the Web API.

• NeuralForecast-based models (nhits, tft, patchtst, nbeatsx) are not installed by requirements.txt or any package extra today; install them manually with pip install neuralforecast torch if you want to experiment with them.

• Conda is a supported way to isolate the install before running the pip commands above.

• Git-backed add-ons stay explicit: pip install -e .[forecast-timesfm] for TimesFM, pip install -e .[patterns-ext] for stock-pattern, pip install -e .[news-ycnbc] for the CNBC adapter, or pip install -e .[all-git] for everything in one go.

• GluonTS/Lag-Llama and GluonTS gt_* methods remain excluded from the supported Python 3.14 environment because upstream runtime constraints are still incompatible.

• Optional accelerators hnswlib and tsdownsample remain excluded from the supported default install, but an opt-in native/source-build path is documented via requirements-optional-src.txt and docs/SETUP.md.

Documentation

New here? Follow this learning path: docs/SETUP.md → docs/GLOSSARY.md → docs/CLI.md → docs/SAMPLE-TRADE.md (then docs/SAMPLE-TRADE-ADVANCED.md and deep dives).

Getting Started

• Setup & Configuration — Installation, MT5 connection, environment variables

• CLI Guide — Command conventions, output formats, help system

• Glossary — Explanations of all technical terms with real-world examples

• Docs Index — One-page map of all docs

Core Topics

• Forecasting — Price prediction methods (Theta, ARIMA, Chronos, etc.)

• Volatility — Estimating price movement magnitude

• Regime Detection — Identifying market states (trending vs. ranging)

• Barrier Analysis — TP/SL hit probability calculation

• Technical Indicators — Available indicators and usage

• Denoising — Smoothing filters to reveal trends

• Pattern Detection — Candlestick and chart patterns

• Temporal Analysis — Session effects, day-of-week, and seasonal patterns

External Data & Options

• Finviz Fundamentals — US equity data, screening, news, calendars

• Options & QuantLib — Options chains, barrier pricing, Heston calibration

Tutorials

• Sample Trade Workflow — Step-by-step analysis for a trade decision

• Advanced Playbook — Regime filters, conformal intervals, barrier optimization

• End-to-End Example — Complete research loop with all tools

Reference

• Environment Variables — Complete .env reference (MT5, MCP, Web API, GPU, etc.)

• Web API — REST endpoints for the Web UI and integrations

• Known Limitations — Practical caveats and documentation gaps

• Troubleshooting — Common issues and fixes

Configuration

Create a .env file in the project root:

MT5_LOGIN=12345678
MT5_PASSWORD=your_password
MT5_SERVER=your_broker_server
MT5_SERVER_TZ=Europe/Athens   # Or use MT5_TIME_OFFSET_MINUTES=120

# Optional trade guardrails
MTDATA_TRADE_GUARDRAILS_ENABLED=1
MTDATA_TRADE_ALLOWED_SYMBOLS=EURUSD,BTCUSD,XAUUSD
MTDATA_TRADE_MAX_VOLUME_BY_SYMBOL=EURUSD:0.50,BTCUSD:0.03
MTDATA_TRADE_MAX_RISK_PCT_OF_EQUITY=1.5

mtdata reads dozens of environment variables covering MT5 connection, timezone, MCP/Web API server settings, news embeddings, Finviz tuning, GPU acceleration, and more. See Environment Variables Reference for the full list, including the trade-guardrail variables and a starter .env template.

Architecture

mtdata/
├── requirements-optional-src.txt  # Opt-in native/source-built accelerators
├── src/mtdata/
│   ├── bootstrap/      # Runtime startup, settings, tool loading
│   ├── core/           # Tool registry, schemas, server logic, MCP tools
│   │   ├── cli/        # Dynamic CLI (argparse) + parsing/, runtime/ subpackages
│   │   ├── data/       # `data_fetch_*` and `wait_event` tools
│   │   ├── regime/     # Regime detection (HMM, BOCPD, MS-AR)
│   │   ├── report/     # `report_generate` runtime
│   │   ├── report_templates/  # Per-style report templates
│   │   ├── reports/    # Shared report helpers
│   │   └── trading/    # `trade_*` tools, account / positions / risk modules
│   ├── forecast/       # Forecasting methods, engines, model store, task manager
│   ├── patterns/       # Pattern detection algorithms
│   ├── services/       # MT5 data access, Finviz, options/news data
│   ├── shared/         # Shared constants, schemas, validators
│   └── utils/          # Shared utilities (indicators, denoising, etc.)
├── webui/              # React + Vite frontend
├── docs/               # Documentation
└── tests/              # Test suite

License

MIT