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).

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 + MetaTrader 5 installed and running (demo account recommended).

# Install dependencies
pip install -r requirements.txt

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

# Fetch recent candles
python cli.py data_fetch_candles EURUSD --timeframe H1 --limit 50

# Generate a baseline price forecast
python cli.py forecast_generate EURUSD --timeframe H1 --horizon 12 --model theta

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

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

• 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/
├── cli.py              # CLI entry point
├── server.py           # MCP server entry point
├── webui.py            # Web API (FastAPI + React UI)
├── src/mtdata/
│   ├── core/           # Tool registry, schemas, server logic
│   ├── forecast/       # Forecasting methods and engines
│   ├── patterns/       # Pattern detection algorithms
│   ├── services/       # MT5 data access layer
│   └── utils/          # Shared utilities
├── webui/              # React + Vite frontend
├── docs/               # Documentation
└── tests/              # Test suite

License

MIT