# mtdata

**Turn MetaTrader 5 into a research lab you can script, query from AI agents, or browse in a local web UI.**

<!-- mcp-name: io.github.emerzon/mtdata-mcp -->

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](docs/MCP.md)), plus a local website and HTTP API.

It is a **toolkit for exploration and automation**, not a trading strategy or financial advice.

---

## Why mtdata?

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

---

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

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

---

## 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](docs/ENV_VARS.md) and [docs/TRADING_SAFETY.md](docs/TRADING_SAFETY.md).

---

## What you can do

| 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](docs/REPORTS.md) | `report_generate` |

**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](docs/FORECAST.md) and [docs/forecast/METHODS.md](docs/forecast/METHODS.md).

---

## Three ways to use it

```text
                    ┌─────────────────┐
                    │  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.

---

## 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](docs/SETUP.md).

```bash
# 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](#web-ui-chart-workspace). Prefer an assistant?
See [MCP.md](docs/MCP.md).

### Web UI (chart workspace)

One path: build the SPA once, start the API, open the UI.

```bash
# 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](docs/WEBUI.md). HTTP reference: [Web API](docs/WEB_API.md) · [Setup](docs/SETUP.md).

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](docs/SETUP.md) |

Dependency caveats (NeuralForecast optional installs, Python 3.14 exclusions, optional native accelerators) live in **[Setup](docs/SETUP.md)** 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](https://pypi.org/project/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](docs/SETUP.md) → [Glossary](docs/GLOSSARY.md) → pick a surface
([Web UI](docs/WEBUI.md) · [CLI](docs/CLI.md) · [AI assistant](docs/MCP.md)) →
[Sample trade](docs/SAMPLE-TRADE.md) or [the same flow in the UI](docs/SAMPLE-TRADE-WEBUI.md).

| Start here | Then explore |
|------------|--------------|
| [Setup](docs/SETUP.md) | [Troubleshooting](docs/TROUBLESHOOTING.md), [Env vars](docs/ENV_VARS.md) |
| [Web UI](docs/WEBUI.md) · [AI assistant (MCP)](docs/MCP.md) · [CLI](docs/CLI.md) | [Glossary](docs/GLOSSARY.md#quick-find), [Market discovery](docs/MARKET.md), [News](docs/NEWS.md) |
| [Sample trade](docs/SAMPLE-TRADE.md) · [Sample trade (UI)](docs/SAMPLE-TRADE-WEBUI.md) | [Trade ideas](docs/TRADE_IDEAS.md), [Advanced playbook](docs/SAMPLE-TRADE-ADVANCED.md), [Example loop](docs/EXAMPLE.md) |
| [Forecasting](docs/FORECAST.md) | [Methods](docs/forecast/METHODS.md), [Backtesting](docs/forecast/BACKTESTING.md), [Uncertainty](docs/forecast/UNCERTAINTY.md) |
| [Regimes](docs/forecast/REGIMES.md) · [Barriers](docs/BARRIER_FUNCTIONS.md) · [Patterns](docs/forecast/PATTERN_SEARCH.md) | [Indicators](docs/TECHNICAL_INDICATORS.md), [Levels](docs/LEVELS.md), [Denoising](docs/DENOISING.md) |
| [Trading safety](docs/TRADING_SAFETY.md) · [Risk analytics](docs/TRADING_RISK.md) | [Wait for events](docs/WAIT_EVENT.md), [Web API](docs/WEB_API.md), [Deployment](docs/DEPLOYMENT.md) |
| [Docs index](docs/README.md) | Full map, tagged User / Operator / Contributor |

---

## Configuration

Create a `.env` in the project root (never commit credentials). Copy [`.env.example`](.env.example) and uncomment what you need.

Full reference: **[docs/ENV_VARS.md](docs/ENV_VARS.md)**.

---

## Project layout

```text
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