Turn MetaTrader 5 into a research lab you can script, query from AI agents, or browse in a local web UI.
mtdata is a Windows-first toolkit that sits on top of a running MT5 terminal. It gives you 80+ tools for market data, forecasting, regime detection, patterns, risk, and trading through the command line and an optional AI-assistant plug (MCP), plus a local website and HTTP API.
It is a toolkit for exploration and automation, not a trading strategy or financial advice.
| Strength | What that means for you |
|---|---|
| One stack, three surfaces | Full tool surface through mtdata-cli and MCP; focused HTTP workflows through a local Web API + React UI |
| Research depth | Classical, ML, and foundation forecasting; regimes; barriers; patterns; 100+ indicators; denoising |
| MT5-native | Candles, ticks, market scans, account/positions, and real order flow against your broker terminal |
| Agent-friendly | Designed for tool-calling workflows: structured outputs, async training, dry-run trading |
| Safety-aware | Demo-first guidance, optional trade guardrails, and dry-run previews on trading commands |
| Guided learning | Sample trade workflows, a glossary, and docs that go from “first candle fetch” to advanced playbooks |
If you already live in MT5 and want repeatable analysis — or you want an assistant to pull data and run forecasts without reinventing the glue — this repo is built for that.
- Learners & discretionary traders — Follow guided workflows without a quant background. Start with candles, a simple forecast, and the sample trade guide.
- Systematic / quant-curious traders — Prototype ideas, backtest, optimize barriers, and automate via CLI or MCP.
- Builders & data folks — Pull MT5 data into pipelines, agents, or a local web stack with a consistent output contract.
| Requirement | Detail |
|---|---|
| Windows | Required to run MetaTrader 5 (and therefore mtdata against MT5) |
| macOS / Linux | Run mtdata on a Windows machine or VM; connect remotely via MCP or Web API |
| Python | 3.14 is the supported runtime for the packaged dependency set |
trade_* tools can place, modify, and close real orders on the account logged into MT5.
- Prefer a demo account until you know the tools and your broker behavior.
- There is no separate paper-trading mode inside mtdata — use an MT5 demo account for simulated execution.
- When a command supports
--dry-run true, use it to preview before anything hits the broker. - For research only, stick to
data_*,forecast_*,regime_*,patterns_*, andreport_*.
Optional guardrails (allowed symbols, max volume, max risk % of equity) are documented in docs/ENV_VARS.md and docs/TRADING_SAFETY.md.
| Area | Highlights | Example tools |
|---|---|---|
| Data | Candles, ticks, depth (optional), market scans | data_fetch_candles, data_fetch_ticks, symbols_top_markets |
| Forecasting | Theta → ARIMA/ML → Chronos-class foundation models; async train & model cache | forecast_generate, forecast_backtest_run, forecast_train |
| Volatility & barriers | Movement estimates; TP/SL hit probabilities via simulation | forecast_volatility_estimate, forecast_barrier_prob |
| Regimes | Trending / ranging / transition; HMM/BOCPD for vol and breaks | regime_detect |
| Patterns & levels | Candlesticks, chart patterns, Elliott/fractals; pivots & confluence | patterns_detect, level tools |
| Indicators & denoise | 100+ technicals; smooth noise to see structure | --indicators, --denoise |
| Multi-asset & diagnostics | Correlation, cointegration, stationarity, outliers, seasonality | correlation_matrix, stationarity_test, outliers_detect |
| Strategy & risk | Simple rule backtests; VaR/CVaR, stress, position sizing | strategy_backtest, trade_var_cvar_calculate |
| Trade ideas | One preview-only research idea: forecast, barriers, size, dry-run | trade_idea_compose |
| Trading | Place/manage orders with guardrails when you opt in | trade_place, trade_close |
| News & fundamentals | Ranked news/calendar; equity screens and issuer dossiers | news, calendar, screener |
| Options | Chains + QuantLib barrier pricing | options_chain, options_barrier_price |
| Reports | Packaged research-style summaries | report_generate |
Notes
market_depth_fetchrequiresMTDATA_ENABLE_MARKET_DEPTH_FETCH=1and broker Level 2/DOM data.- Options chains default to Yahoo Finance; Tradier is available with env config. Pure QuantLib pricing does not need a chain provider.
For method-level detail, see docs/FORECAST.md and docs/forecast/METHODS.md.
┌─────────────────┐
│ MetaTrader 5 │
│ (Windows) │
└────────┬────────┘
│
┌──────▼──────┐
│ mtdata │
└──────┬──────┘
┌─────────────────┼─────────────────┐
▼ ▼ ▼
mtdata-cli MCP server Web API
(scripts, REPL) (AI assistants) (+ React UI)
| Surface | Entry point | Good for |
|---|---|---|
| CLI | mtdata-cli |
Scripts, exploration, copy-paste workflows |
| MCP | mtdata-stdio / mtdata-sse / mtdata-streamable-http |
Agent tool use (Claude, Cursor, custom clients) |
| Web UI + API | mtdata-webapi |
Chart workspace at /app, REST for apps and notebooks |
All three are first-class delivery surfaces. Pick CLI, MCP, or Web UI for the same research stack.
Prerequisites: Windows + Python 3.14 + MetaTrader 5 installed and running (demo account recommended). That is enough for the first candle fetch.
Optional compiler note (you can skip this on day one): the full research stack may need Visual Studio Build Tools 2022 with Desktop development with C++ because some packages source-build on Python 3.14. Details live in Setup.
# Optional: isolate the environment
conda create -n mtdata python=3.14 -y
conda activate mtdata
# Lean core (data, indicators, core analysis)
pip install -e .
# Confirm MetaTrader 5 sees your terminal (read-only)
mtdata-cli symbols_list --limit 5
# Pull candles (one bar per hour, last 50 hours)
mtdata-cli data_fetch_candles EURUSD --timeframe H1 --limit 50
# A simple baseline forecast — an estimate, not a guarantee
mtdata-cli forecast_generate EURUSD --timeframe H1 --horizon 12 --method thetaPrefer a website? Jump to Web UI. Prefer an assistant? See MCP.md.
One path: build the SPA once, start the API, open the UI.
# Web extra if you installed lean core only
pip install -e ".[web]"
# Production frontend (once per checkout / after UI changes)
cd webui && npm ci && npm run build && cd ..
# Start API + UI
mtdata-webapi
# → open http://127.0.0.1:8000/app/Run mtdata-webapi from the repository root (or set WEBUI_DIST_DIR to an absolute path). If webui/dist is missing, the API still starts and /app returns a clear enablement page (build steps above). Live UI development: cd webui && npm run dev (proxies /api to :8000). User tour: Web UI. HTTP reference: Web API · Setup.
Keep the first session read-only unless you are on a demo account and intentionally testing trading.
Install flavors (summary)
| Goal | Command |
|---|---|
| Lean core | pip install -e . |
| Full docs-aligned stack | pip install -r requirements.txt |
| Web only | pip install -e .[web] |
| Classical / foundation forecast extras | pip install -e .[forecast-classical] / pip install -e .[forecast-foundation] |
| TimesFM / Git-manual add-ons | See docs/SETUP.md |
Dependency caveats (NeuralForecast optional installs, Python 3.14 exclusions, optional native accelerators) live in Setup so this page stays focused on getting you productive.
The PyPI package is mtdata-mcp. The command-line entry is mtdata-cli (not mtdata). That avoids a clash with the unrelated mtdata machine-translation dataset package, which already owns the mtdata CLI. The importable Python package remains mtdata (import mtdata). If mtdata-cli is not on PATH after install, activate the same environment and use python -m mtdata instead. IDE and assistant configs should still launch mtdata-stdio. A mtdata-mcp console-script alias points at the same stdio entry so Official MCP Registry clients that compose uvx mtdata-mcp start that server.
Suggested path: Setup → Glossary → pick a surface (Web UI · CLI · AI assistant) → Sample trade or the same flow in the UI.
| Start here | Then explore |
|---|---|
| Setup | Troubleshooting, Env vars |
| Web UI · AI assistant (MCP) · CLI | Glossary, Market discovery, News |
| Sample trade · Sample trade (UI) | Trade ideas, Advanced playbook, Example loop |
| Forecasting | Methods, Backtesting, Uncertainty |
| Regimes · Barriers · Patterns | Indicators, Levels, Denoising |
| Trading safety · Risk analytics | Wait for events, Web API, Deployment |
| Docs index | Full map, tagged User / Operator / Contributor |
Create a .env in the project root (never commit credentials). Copy .env.example and uncomment what you need.
Full reference: docs/ENV_VARS.md.
mtdata/
├── src/mtdata/
│ ├── bootstrap/ # Runtime init, settings, tool loading
│ ├── core/ # CLI, MCP/server, trading, regime, report tools
│ ├── forecast/ # Engines, methods, model store, async tasks
│ ├── patterns/ # Chart / candlestick / structure detection
│ ├── services/ # MT5 gateway, Finviz, options, news
│ ├── shared/ # Schemas and shared constants
│ └── utils/ # Indicators, denoising, helpers
├── webui/ # React + Vite frontend
├── docs/ # User guides and references
└── tests/ # Pytest suite
MIT