MT5 MCP Server

Let your AI assistant trade MetaTrader 5 — safely.

An MCP server that gives AI assistants (Claude Desktop, Claude Code, ZCode, Cursor, ...) full access to a MetaTrader 5 terminal: market data, indicators, order placement, position management and trade history — with a dry-run safety mode that is ON by default.

You:  "What's my account status?"
AI:   Balance $10,000 · Equity $10,050 · 1 open XAUUSD position (+$12.40)

You:  "Buy 0.1 lots XAUUSD with stop loss at 2390"
AI:   ✓ Validated: volume 0.1 ✓ Filling mode FOK ✓ Within MT5_MAX_VOLUME
      ⚠ Dry-run mode is ON — no real order sent. Set MT5_DRY_RUN=false to trade.

Highlights

• 🔒 Dry-run by default — every order tool validates and previews without sending. Real trading is one env var away, never an accident.

• 🛡 Guard rails — volume rounded to the symbol's lot step, capped by MT5_MAX_VOLUME, human-readable error messages for every MT5 return code (no more mystery retcode 10016).

• 📊 Built-in indicators — SMA, EMA, RSI, ATR computed from candles, no extra dependencies.

• ⚖️ Risk-based lot sizing — calculate_lot_size tells you exactly how many lots to risk 1% of your account.

• 🔌 Two connection modes — attach to your already-running terminal, or log in via environment variables.

• ✅ Tested — 30+ tests run against a simulated MT5 terminal, so the whole suite passes even without MT5 installed.

Related MCP server: MetaTrader 5 MCP Server

Requirements

• Windows (the MetaTrader5 Python package is Windows-only) + a MetaTrader 5 terminal installed and logged in

• "Algo Trading" enabled in the MT5 terminal (button in the toolbar)

• Python 3.10+

Quick start

1. Install

pip install mt5-mcp-server

Or with uv:

uvx mt5-mcp-server

2. Add to your MCP client

Claude Desktop — %APPDATA%\Claude\claude_desktop_config.json (full example in examples/):

{
  "mcpServers": {
    "mt5": {
      "command": "mt5-mcp-server",
      "env": {
        "MT5_DRY_RUN": "true",
        "MT5_LOGIN": "12345678",
        "MT5_PASSWORD": "your-password",
        "MT5_SERVER": "YourBroker-Server"
      }
    }
  }
}

Claude Code / ZCode:

claude mcp add mt5 --env MT5_DRY_RUN=true -- mt5-mcp-server

Leave MT5_LOGIN out to attach to whichever account is already logged in inside the running terminal.

3. Try it (safe — dry-run is on)

Ask your assistant: "What's my account balance?" then "Buy 0.1 lots XAUUSD". You will get a validated preview, not a real order.

4. Enable real trading

Set "MT5_DRY_RUN": "false" in the config. Test on a demo account first.

Configuration

Tools

Account — get_account_info · get_terminal_info

Market data — search_symbols · get_symbol_info · get_tick · get_candles (M1→MN1) · get_indicator (SMA / EMA / RSI / ATR)

Portfolio — get_positions (live P/L) · get_pending_orders · get_history (net profit, wins/losses per symbol)

Orders — place_market_order · place_pending_order (limit/stop) · close_position (full or partial) · modify_position (SL/TP) · modify_pending_order · cancel_pending_order

Risk — calculate_lot_size (position size from risk % + stop loss)

Safety model

1. Dry-run first: MT5_DRY_RUN=true (default) validates the order against symbol rules and returns exactly what would be sent.

2. Volume guard: lots are rounded down to the symbol's step and capped by MT5_MAX_VOLUME; volumes below the symbol minimum are rejected.

3. Clear errors: every broker rejection is translated into plain language (retcode 10016 → "SL/TP is too close to the price or on the wrong side").

4. No keys in code: credentials go in MCP client env config, never in the repository.

⚠️ Trading involves risk. This software is provided as-is, with no warranty. Always test on a demo account first. The authors are not responsible for trading losses.

Example session

User: What's my exposure right now?

AI: (calls get_positions) You have 2 open positions: 0.10 XAUUSD buy (+$12.40) and 0.05 EURUSD sell (−$3.10). Floating P/L: +$9.30.

User: Close half of the gold position.

AI: (calls close_position ticket=X, volume=0.05) ✓ Closed 0.05 lots at 2401.10. Remaining: 0.05 lots.

Development

git clone https://github.com/Erfangit23/mt5-mcp-server
cd mt5-mcp-server
pip install -e ".[dev]"
pytest -v

Tests run against a simulated MT5 terminal (tests/fake_mt5.py) — no MT5 installation needed. To verify the MCP handshake with a real terminal, run python scripts/smoke_test.py.

راهنمای سریع (فارسی)

۱. نصب: pip install mt5-mcp-server ۲. در کلود دسکتاپ، فایل claude_desktop_config.json را مثل بالا تنظیم کنید. ۳. حالت Dry-Run به‌صورت پیش‌فرض روشن است؛ هیچ معامله واقعی انجام نمی‌شود. ۴. برای معامله واقعی: MT5_DRY_RUN را false کنید — اول روی حساب دمو تست کنید. ۵. دکمه Algo Trading در ترمینال MT5 باید فعال باشد.

Roadmap

• Streaming tick prices (MCP subscriptions)

• Chart screenshots via terminal

• MACD / Bollinger Bands indicators

• Linux support via Wine bridge

License

MIT — use it, fork it, ship it.