Metadata-Version: 2.4
Name: mtdata-mcp
Version: 0.1.0
Summary: MetaTrader5 MCP Server for market data retrieval and analysis.
Author-email: Emerson Gomes <emerson.gomes@gmail.com>
Project-URL: Homepage, https://github.com/emerzon/mtdata-mcp
Project-URL: Repository, https://github.com/emerzon/mtdata-mcp
Project-URL: Issues, https://github.com/emerzon/mtdata-mcp/issues
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Financial and Insurance Industry
Classifier: Topic :: Office/Business :: Financial :: Investment
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.14
Requires-Python: >=3.14
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: MetaTrader5>=5.0.6090
Requires-Dist: mcp<2,>=1.29.0
Requires-Dist: typing-extensions>=4.16.0
Requires-Dist: python-dotenv>=1.2.3
Requires-Dist: dateparser>=1.4.2
Requires-Dist: tzlocal>=5.4.4
Requires-Dist: pandas<3,>=2.3.3
Requires-Dist: numpy<2.5,>=2.4.6
Requires-Dist: pandas-ta-classic>=0.6.52
Requires-Dist: holidays>=0.103
Requires-Dist: scipy>=1.18.1
Requires-Dist: scikit-learn<1.8,>=1.7.2
Requires-Dist: hmmlearn>=0.3.3
Requires-Dist: scikit-image>=0.26.0
Requires-Dist: PyWavelets>=1.9.0
Requires-Dist: EMD-signal>=1.10.0
Requires-Dist: vmdpy>=0.2
Requires-Dist: ruptures<1.1.0,>=1.0.6
Requires-Dist: statsmodels>=0.14.6
Requires-Dist: tslearn>=0.9.0
Requires-Dist: stumpy>=1.14.1
Requires-Dist: finvizfinance>=1.3.0
Requires-Dist: requests>=2.32.0
Provides-Extra: forecast-classical
Requires-Dist: arch>=8.0.0; extra == "forecast-classical"
Requires-Dist: optuna>=4.9.0; extra == "forecast-classical"
Requires-Dist: QuantLib>=1.43; extra == "forecast-classical"
Requires-Dist: statsforecast<3,>=2.1.1; extra == "forecast-classical"
Requires-Dist: sktime>=1.1.0; extra == "forecast-classical"
Requires-Dist: mlforecast>=1.1.0; extra == "forecast-classical"
Requires-Dist: lightgbm>=4.7.0; extra == "forecast-classical"
Requires-Dist: coreforecast>=0.0.18; extra == "forecast-classical"
Requires-Dist: fugue>=0.9.7; extra == "forecast-classical"
Requires-Dist: numba>=0.67.0; extra == "forecast-classical"
Requires-Dist: tsfresh>=0.21.2; extra == "forecast-classical"
Provides-Extra: forecast-foundation
Requires-Dist: torch<3,>=2.13.0; extra == "forecast-foundation"
Requires-Dist: pillow>=12.3.0; extra == "forecast-foundation"
Requires-Dist: accelerate>=1.14.0; extra == "forecast-foundation"
Requires-Dist: chronos-forecasting>=2.3.1; extra == "forecast-foundation"
Requires-Dist: transformers<6,>=5.15.1; extra == "forecast-foundation"
Requires-Dist: huggingface-hub<2,>=1.28.0; extra == "forecast-foundation"
Provides-Extra: forecast-timesfm
Requires-Dist: torch<3,>=2.13.0; extra == "forecast-timesfm"
Requires-Dist: timesfm[torch]<3,>=2.0.2; extra == "forecast-timesfm"
Provides-Extra: patterns-ext
Provides-Extra: pattern-search-hnsw
Requires-Dist: hnswlib==0.8.0; extra == "pattern-search-hnsw"
Provides-Extra: web
Requires-Dist: fastapi>=0.141.1; extra == "web"
Requires-Dist: uvicorn[standard]>=0.52.4; extra == "web"
Provides-Extra: news-embeddings
Requires-Dist: sentence-transformers<6,>=5.7.0; extra == "news-embeddings"
Requires-Dist: huggingface-hub<2,>=1.28.0; extra == "news-embeddings"
Provides-Extra: news-ycnbc
Requires-Dist: ycnbc>=1.0.12; extra == "news-ycnbc"
Provides-Extra: dimred-ext
Requires-Dist: umap-learn>=0.5.12; extra == "dimred-ext"
Provides-Extra: all
Requires-Dist: arch>=8.0.0; extra == "all"
Requires-Dist: optuna>=4.9.0; extra == "all"
Requires-Dist: QuantLib>=1.43; extra == "all"
Requires-Dist: statsforecast<3,>=2.1.1; extra == "all"
Requires-Dist: sktime>=1.1.0; extra == "all"
Requires-Dist: mlforecast>=1.1.0; extra == "all"
Requires-Dist: lightgbm>=4.7.0; extra == "all"
Requires-Dist: coreforecast>=0.0.18; extra == "all"
Requires-Dist: fugue>=0.9.7; extra == "all"
Requires-Dist: numba>=0.67.0; extra == "all"
Requires-Dist: tsfresh>=0.21.2; extra == "all"
Requires-Dist: torch<3,>=2.13.0; extra == "all"
Requires-Dist: pillow>=12.3.0; extra == "all"
Requires-Dist: accelerate>=1.14.0; extra == "all"
Requires-Dist: chronos-forecasting>=2.3.1; extra == "all"
Requires-Dist: transformers<6,>=5.15.1; extra == "all"
Requires-Dist: huggingface-hub<2,>=1.28.0; extra == "all"
Requires-Dist: timesfm[torch]<3,>=2.0.2; extra == "all"
Requires-Dist: tsdownsample>=0.1.5.1; extra == "all"
Requires-Dist: hnswlib==0.8.0; extra == "all"
Requires-Dist: fastapi>=0.141.1; extra == "all"
Requires-Dist: uvicorn[standard]>=0.52.4; extra == "all"
Requires-Dist: sentence-transformers<6,>=5.7.0; extra == "all"
Requires-Dist: umap-learn>=0.5.12; extra == "all"
Provides-Extra: all-git
Requires-Dist: arch>=8.0.0; extra == "all-git"
Requires-Dist: optuna>=4.9.0; extra == "all-git"
Requires-Dist: QuantLib>=1.43; extra == "all-git"
Requires-Dist: statsforecast<3,>=2.1.1; extra == "all-git"
Requires-Dist: sktime>=1.1.0; extra == "all-git"
Requires-Dist: mlforecast>=1.1.0; extra == "all-git"
Requires-Dist: lightgbm>=4.7.0; extra == "all-git"
Requires-Dist: coreforecast>=0.0.18; extra == "all-git"
Requires-Dist: fugue>=0.9.7; extra == "all-git"
Requires-Dist: numba>=0.67.0; extra == "all-git"
Requires-Dist: tsfresh>=0.21.2; extra == "all-git"
Requires-Dist: torch<3,>=2.13.0; extra == "all-git"
Requires-Dist: pillow>=12.3.0; extra == "all-git"
Requires-Dist: accelerate>=1.14.0; extra == "all-git"
Requires-Dist: chronos-forecasting>=2.3.1; extra == "all-git"
Requires-Dist: transformers<6,>=5.15.1; extra == "all-git"
Requires-Dist: huggingface-hub<2,>=1.28.0; extra == "all-git"
Requires-Dist: timesfm[torch]<3,>=2.0.2; extra == "all-git"
Requires-Dist: tsdownsample>=0.1.5.1; extra == "all-git"
Requires-Dist: hnswlib==0.8.0; extra == "all-git"
Requires-Dist: fastapi>=0.141.1; extra == "all-git"
Requires-Dist: uvicorn[standard]>=0.52.4; extra == "all-git"
Requires-Dist: sentence-transformers<6,>=5.7.0; extra == "all-git"
Requires-Dist: umap-learn>=0.5.12; extra == "all-git"
Requires-Dist: ycnbc>=1.0.12; extra == "all-git"
Dynamic: license-file

# 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 / stress-style market states | `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/
```

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

```ini
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](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
