mtdata

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.

---

Why mtdata?

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.

---

Who is this for?

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

---

Platform notes

---

Safety first

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_*, and report_*.

Optional guardrails (allowed symbols, max volume, max risk % of equity) are documented in docs/ENV_VARS.md and docs/TRADING_SAFETY.md.

---

What you can do

Notes

• market_depth_fetch requires MTDATA_ENABLE_MARKET_DEPTH_FETCH=1 and 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.

---

Three ways to use it

                    ┌─────────────────┐
                    │  MetaTrader 5   │
                    │   (Windows)     │
                    └────────┬────────┘
                             │
                      ┌──────▼──────┐
                      │   mtdata    │
                      └──────┬──────┘
           ┌─────────────────┼─────────────────┐
           ▼                 ▼                 ▼
      mtdata-cli          MCP server        Web API
   (scripts, REPL)    (AI assistants)    (+ React UI)

All three are first-class delivery surfaces. Pick CLI, MCP, or Web UI for the same research stack.

---

Quick start

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 theta

Prefer a website? Jump to Web UI. Prefer an assistant? See MCP.md.

Web UI (chart workspace)

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)

Dependency caveats (NeuralForecast optional installs, Python 3.14 exclusions, optional native accelerators) live in Setup so this page stays focused on getting you productive.

Naming

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.

---

Documentation

Suggested path: Setup → Glossary → pick a surface (Web UI · CLI · AI assistant) → Sample trade or the same flow in the UI.

---

Configuration

Create a .env in the project root (never commit credentials):

MT5_LOGIN=12345678
MT5_PASSWORD=your_password
MT5_SERVER=your_broker_server
MT5_SERVER_TZ=Europe/Athens   # optional broker session/calendar timezone

# 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

Full reference: docs/ENV_VARS.md.

---

Project layout

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

---

License

MIT