mtdata

mtdata is a research and automation toolkit for MetaTrader 5 (MT5). It provides tools for forecasting, regime detection, signal processing, risk analysis, and reporting—bridging raw market data with data science.

It runs as a Model Context Protocol (MCP) server or a standalone CLI.

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.

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

Capabilities

Quick Start

Prerequisites: Windows + Python 3.14 + MetaTrader 5 installed and running (demo account recommended).

# Lean core install
pip install -e .

# Full 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

Notes:

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

• pip install -r requirements.txt installs the full validated Python 3.14 stack, including Chronos/TimesFM, StatsForecast, sktime, mlforecast, and the Web API.

• gluonts/Lag-Llama, hnswlib, and tsdownsample are intentionally excluded from the default 3.14 environment because current wheel support is incomplete or incompatible.

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

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

• 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_TIME_OFFSET_MINUTES=0  # Adjust if broker server time differs from UTC

Architecture

mtdata/
├── src/mtdata/
│   ├── core/           # Tool registry, schemas, server logic, all 52 MCP tools
│   ├── forecast/       # Forecasting methods, engines, and method registry
│   ├── patterns/       # Pattern detection algorithms
│   ├── services/       # MT5 data access, Finviz, options data
│   └── utils/          # Shared utilities (indicators, denoising, etc.)
├── webui/              # React + Vite frontend
├── docs/               # Documentation
└── tests/              # Test suite

License

MIT