# MT5 MCP Server

A local MCP server that connects a MetaTrader 5 terminal to Claude.
It reads market data, account state and history, captures chart screenshots,
and can send **live orders**.

## Requirements

1. The MetaTrader 5 terminal must be **running**
2. **Tools → Options → Expert Advisors → "Allow algorithmic trading"** must be enabled
3. An account must be logged in

If the terminal is closed, every tool returns `MT5 initialize failed` — open it and retry.

## Install

```bash
uv venv --python 3.12 .venv
uv pip install --python .venv/Scripts/python.exe -r requirements.txt
```

Then adjust the paths in [.mcp.json](.mcp.json) and restart Claude Code.

## Tools (20)

### Market data

| Tool | What it does |
|---|---|
| `mt5_status` | Terminal build, connection, account, balance, equity, margin, DEMO/REAL |
| `list_symbols` | Search symbols — wildcards supported (`EUR*`, `*USD*`) |
| `symbol_info` | Digits, point, spread, contract size, lot limits, margin and swap rates |
| `get_ticks` | Live bid/ask and spread for one or more symbols |
| `get_candles` | OHLCV from M1 to MN1, by count or by date range |
| `get_tick_history` | Raw bid/ask tick stream, useful for backtesting |

### Account

| Tool | What it does |
|---|---|
| `get_positions` | Open positions and total floating P/L |
| `get_pending_orders` | Active limit and stop orders |
| `get_history_deals` | Closed trades with profit, commission and swap totals |
| `get_history_orders` | Orders that were placed, cancelled or rejected |
| `calc_trade` | Margin and expected profit **before** sending anything (no order is placed) |

### Screen capture

| Tool | What it does |
|---|---|
| `list_charts` | Open charts with symbol, timeframe and size |
| `screenshot` | PNG of the terminal window or of a single chart |

`screenshot` does not come from the MetaTrader5 Python API — that API has no
screenshot function at all. It is built on the Windows `PrintWindow` call
([mt5_capture.py](mt5_capture.py)). It works on a background window, but
**not on a minimised one**.

Pass `target='window'` for the whole terminal, or `target='XAUUSD,M30'` for one
chart. Passing just `'XAUUSD'` picks the largest chart for that symbol.

### Trading — live

| Tool | What it does |
|---|---|
| `open_position` | Market buy/sell, SL/TP as absolute price or in points |
| `place_pending_order` | Buy/sell limit or stop, with optional expiry |
| `modify_position` | Change SL/TP on an open position |
| `modify_pending_order` | Change price, SL or TP on a pending order |
| `close_position` | Full or partial close |
| `cancel_pending_order` | Remove a pending order |
| `close_all_positions` | Close everything, or only one symbol |

> ⚠️ There is no demo/real guard on the trading tools. Orders go to whichever
> account the terminal is logged into. The broker's filling mode is detected
> automatically and the symbol is added to Market Watch as needed.

## CLI ([trade.py](trade.py))

The same tools without Claude, straight from the command line:

```bash
.venv/Scripts/python.exe trade.py buy XAUUSD 0.01 --sl-points 500 --tp-points 1000
.venv/Scripts/python.exe trade.py modify 10090941191 --sl 4345.56 --tp 4360.56
.venv/Scripts/python.exe trade.py close 10090941191
.venv/Scripts/python.exe trade.py close-all --symbol XAUUSD
.venv/Scripts/python.exe trade.py positions
.venv/Scripts/python.exe trade.py calc buy XAUUSD 0.01 --close-price 4360
```

Run `trade.py --help` for every subcommand.

## Time format

All time inputs are UTC: `YYYY-MM-DD`, `YYYY-MM-DD HH:MM`, or
`YYYY-MM-DD HH:MM:SS`. Output timestamps are UTC as well.

## Configuration

These environment variables are optional in `.mcp.json`:

| Variable | Purpose |
|---|---|
| `MT5_PATH` | Path to `terminal64.exe`, used to launch the terminal if it is closed |
| `MT5_LOGIN` / `MT5_PASSWORD` / `MT5_SERVER` | Log into a different account (default: whatever the terminal already uses) |

## Smoke test

```bash
.venv/Scripts/python.exe -c "import mt5_mcp_server as s; print(s.mt5_status()['account'])"
```