MT5 MCP Server

Custom Model Context Protocol (MCP) server that connects Claude Desktop directly to MetaTrader 5. Lets Claude pull historical/live data, run backtests, inspect your account, and place orders with mandatory two-step confirmation.

Features

• Historical data: OHLCV candles, raw ticks, symbol contract specs

• Real-time quotes: bid/ask/spread, market depth, live tick monitoring

• Account inspection: balance, equity, open positions, pending orders, deal history

• Order management: market & pending orders, position close, SL/TP modify — all with token-based confirmation

• Backtesting: vectorized signal-based engine with EMA/SMA/RSI/cross helpers, returns Sharpe, drawdown, profit factor, win rate

• Safety gateway: lot-size limits, per-session order cap, demo-only enforcement by default

Related MCP server: MetaTrader 5 MCP Server

Requirements

• Windows (MetaTrader5 Python package is Windows-only)

• Python 3.13 or newer

• MetaTrader 5 desktop terminal, logged into a broker account

• Claude Desktop

Installation

1. Place the project

Copy the entire mt5_mcp_server folder to a permanent location, for example:

C:\Users\YourName\mt5_mcp_server\

2. Install Python dependencies

Open PowerShell in the project folder and run:

pip install -r requirements.txt

3. Configure environment

Copy .env.example to .env and edit if you need custom settings. The defaults are safe (demo-only, 1.0 lot max, 20 orders per session, confirmation required).

copy .env.example .env

If your MT5 terminal is already logged in, you can leave login/password blank — the server will use the active session.

4. Configure MT5 to allow algorithmic trading

In MetaTrader 5:

1. Tools → Options → Expert Advisors

2. Check "Allow algorithmic trading"

3. Check "Allow DLL imports" (for the Python integration)

4. Click OK

5. Run the connection test

python test_connection.py

You should see [OK] on every check. If any check fails, fix it before registering the MCP server with Claude Desktop.

6. Register with Claude Desktop

Open Claude Desktop's config file:

• Windows: %APPDATA%\Claude\claude_desktop_config.json

Merge in the MCP server entry from claude_desktop_config.example.json, adjusting paths to match your install. A minimal example:

{
  "mcpServers": {
    "mt5": {
      "command": "python",
      "args": ["C:\\Users\\YourName\\mt5_mcp_server\\server.py"],
      "env": {
        "PYTHONPATH": "C:\\Users\\YourName\\mt5_mcp_server",
        "SAFETY_MODE": "demo",
        "MAX_LOT_SIZE": "0.1"
      }
    }
  }
}

Restart Claude Desktop. The mt5 server should now appear in the connectors list, and Claude can call its tools.

Available Tools

Connection

• mt5_info — terminal + account info

• safety_status — current safety config & session counters

Historical Data

• get_ohlcv(symbol, timeframe, count|start, end) — OHLCV bars

• get_ticks(symbol, count|start, end) — raw ticks

• get_symbol_info(symbol) — contract specs

• list_symbols(group?) — broker symbol list

Real-time

• get_current_price(symbol) — bid/ask/spread snapshot

• get_market_depth(symbol) — DOM (broker-dependent)

• monitor_symbol(symbol, duration_seconds) — sample live ticks (max 30s)

Account & Positions (read-only)

• get_account_info() — balance, equity, margin, leverage

• get_positions(symbol?) — open positions

• get_orders(symbol?) — pending orders

• get_history(days) — closed deals over last N days

Order Operations (two-step)

Every write operation requires prepare_* then confirm_* with the token:

• prepare_order / confirm_order — open new market or pending order

• prepare_close_position / confirm_close_position — close (full or partial)

• prepare_modify_position / confirm_modify_position — change SL/TP

Backtesting

• run_backtest(symbol, timeframe, buy_when, sell_when, ...) — vectorized backtest

• calculate_metrics(trades, initial_balance) — performance metrics

Backtest signal expressions support:

• sma(close, n), ema(close, n), rsi(close, n)

• cross_above(a, b), cross_below(a, b), shift(s, n)

• References: open, high, low, close, volume

Example:

buy_when:  cross_above(ema(close, 12), ema(close, 26)) & (rsi(close, 14) < 70)
sell_when: cross_below(ema(close, 12), ema(close, 26))

Safety Architecture

The server is designed to make accidental order placement very hard:

1. Demo enforcement. SAFETY_MODE=demo (default) refuses to operate if the logged-in account is not demo. This catches the most common foot-gun.

2. Two-step orders. Every trade-modifying tool is split into prepare_* and confirm_*. The prepare step returns a one-time token that's bound to exact parameters. The confirm step validates the token + that the params match. This means a single rogue tool call cannot place an order — Claude must first call prepare, show you the summary, wait for your "go ahead", then call confirm with the token. Tokens expire after 5 minutes.

3. Lot-size limit. MAX_LOT_SIZE (default 1.0) caps any single order's volume.

4. Per-session cap. MAX_ORDERS_PER_SESSION (default 20) prevents runaway loops from filling your account with trades. Resets on server restart.

5. Broker-side validation. All orders go through MT5's own validation (volume_min/max, allowed trade modes, margin checks).

Going to live trading

When you're ready (after substantial demo testing), edit .env:

SAFETY_MODE=live
MAX_LOT_SIZE=0.05    # start TINY on real money

The two-step confirmation flow stays in place — there is intentionally no way to disable it.

Troubleshooting

"MT5 initialize() failed" — Make sure the MT5 desktop terminal is running and logged in. The Python package attaches to a running terminal; it doesn't launch one. Try setting MT5_TERMINAL_PATH in .env if auto-detect fails.

"Symbol 'XXXUSD' not found" — The symbol must exist for your broker. Use list_symbols(group="*USD*") to see what's available. Some brokers add suffixes like EURUSD.r or EURUSD-pro.

Server doesn't appear in Claude Desktop — Check the path in claude_desktop_config.json is absolute and uses double backslashes on Windows. Check Claude Desktop's developer logs (Help → View Logs) for spawn errors.

"SAFETY: account is REAL" — You connected a live account but SAFETY_MODE=demo. This is intentional protection. Either log into a demo account in MT5, or set SAFETY_MODE=live in .env (only after you've thoroughly tested).

Ticks/quotes empty during weekend — Forex market is closed Friday evening to Sunday evening (UTC). Historical data still works.

Development workflow

The recommended Claude flow when building a new strategy:

1. "Pull the last 5000 H1 EURUSD bars" — get_ohlcv

2. "Try a 12/26 EMA crossover strategy" — run_backtest

3. "Show me the metrics broken down by year" — Claude analyses returned trade list

4. "Tighten the SL to 30 points and retest" — iterate

5. "Once happy, draft the equivalent MQL5 EA file" — Claude writes .mq5 to your MQL5/Experts/ folder via the FileSystem connector

6. "Open a 0.01 lot demo BUY at market with 30-point SL" — prepare_order → you review → confirm_order

License

MIT