mtdata — turn MetaTrader 5 into your quantitative research lab

mtdata is a Windows-focused financial research toolkit built on top of MetaTrader 5, providing three interfaces over the same backend:

Interface	What it's for
mtdata-cli	Scriptable command-line access to every tool
MCP server	Direct tool access for AI assistants (Claude, Cursor, Trae, …)
Web UI / Web API	Browser-based charting workbench and HTTP API

It exposes 82 tools covering data fetching, forecasting, market-regime detection, pattern recognition, risk analysis, and trade execution, all behind one unified set of tool definitions.

⚠️ mtdata is a research and exploration toolkit, not a trading strategy and not investment advice.

---

Quick start

# Install (editable, for development)
py -3.14 -m pip install -e ".[web,pattern-search-hnsw]"

# Verify the MT5 connection
mtdata-cli symbols_list --limit 5

# Fetch candles (optionally alongside indicators)
mtdata-cli data_fetch_candles EURUSD --timeframe H1 --limit 50
mtdata-cli data_fetch_candles EURUSD --timeframe H1 --limit 50 --indicators rsi macd

# Forecast the next N bars (Theta is the lightweight default)
mtdata-cli forecast_generate EURUSD --timeframe H1 --horizon 12 --method theta

# Detect chart patterns and market regimes
mtdata-cli patterns_detect EURUSD --timeframe H1 --mode candlestick
mtdata-cli regime_detect EURUSD --timeframe H1 --method bocpd

# Backtest a simple indicator strategy
mtdata-cli strategy_backtest EURUSD --timeframe H1 --strategy sma_cross --lookback 500

# Generate a research report / check the news / list all tools
mtdata-cli report_generate EURUSD --timeframe H1 --template basic
mtdata-cli news EURUSD
mtdata-cli tools_list

Technical indicators (193)

All indicators come from pandas-ta-classic (v0.6.52+) and can be attached to candle fetches via --indicators:

# Search the catalog
mtdata-cli indicators_list --category momentum
mtdata-cli indicators_list --search "moving average"

The full catalog (193 indicators across 9 categories: momentum, overlap, trend, volume, volatility, statistics, cycles, candles, performance) is documented in 指标列表.md.

Prediction methods (71)

forecast_generate supports 71 forecasting methods across libraries — classical (theta, naive, fourier_ols), ETS/ARIMA, StatsForecast, machine learning, Monte Carlo, pretrained foundation models (Chronos, TimesFM), sktime, and neural networks:

mtdata-cli forecast_generate EURUSD --timeframe H1 --horizon 24 --method sf_autoarima
mtdata-cli forecast_barrier_prob EURUSD --timeframe H1 --horizon 12 --direction long \
  --barrier 'kind=tp_sl,unit=pct,take_profit=0.40,stop_loss=0.60' --json

Safety first

The trade_* tools can place, modify, and close live orders.

• Always use a demo account until you fully trust the tool and your broker.
• Trading commands default to --dry-run true (preview); pass --dry-run false only when you intend to execute.
• Turn on trade guardrails: MTDATA_TRADE_GUARDRAILS_ENABLED=1
• For research only, stick to data_*, forecast_*, regime_*, patterns_*, and report_* tools.
• See docs/TRADING_SAFETY.md for the full safety model.

Configuration

Copy .env.example to .env in the project root. Notable variables:

MT5_SERVER_TZ=Europe/Athens      # broker server timezone
CLIENT_TZ=Asia/Shanghai          # local timezone
MCP_TRANSPORT=sse                # or stdio
FASTMCP_HOST=127.0.0.1
FASTMCP_PORT=8765
WEBAPI_HOST=127.0.0.1
WEBAPI_PORT=8766
MTDATA_TRADE_GUARDRAILS_ENABLED=1

Full reference: docs/ENV_VARS.md.

---

Documentation

Start here: docs/SETUP.md → docs/GLOSSARY.md

Topic	Guide
CLI	docs/CLI.md
MCP for AI assistants	docs/MCP.md
Web UI	docs/WEBUI.md
Forecasting	docs/FORECAST.md · docs/forecast/METHODS.md · docs/forecast/BACKTESTING.md
Bar / TP-SL probability	docs/BARRIER_FUNCTIONS.md
Regime & pattern analysis	docs/forecast/REGIMES.md · docs/forecast/PATTERN_SEARCH.md
Trading safety & risk	docs/TRADING_SAFETY.md · docs/TRADING_RISK.md
自动交易执行壳 / 研究管线	trading/README.md · research/README.md
Worked examples	docs/SAMPLE-TRADE.md · docs/SAMPLE-TRADE-ADVANCED.md · docs/EXAMPLE.md
Indicators	指标列表.md (complete catalog, with trading context)
中文文档	README_CN.md

Project layout

src/mtdata/
├── bootstrap/     # runtime init, env vars, tool loading
├── core/          # CLI, MCP/Web servers, trading, regime, reports
├── forecast/      # forecasting engine, methods, model store, async tasks
├── patterns/      # candlestick / classic / harmonic / Elliott detection
├── services/      # MT5 gateway, Finviz, options, news
├── shared/        # shared types, schemas, constants
└── utils/         # indicators, denoising, helpers
webui/             # React + Vite frontend
trading/           # your auto-trading shell: signal loop, risk library, dry-run tiers
research/          # your offline research pipeline: fetch → features → train → evaluate
docs/              # documentation (40+ guides)
tests/             # test suite

License

MIT