MTX

  ███╗   ███╗████████╗██╗  ██╗
  ████╗ ████║╚══██╔══╝╚██╗██╔╝
  ██╔████╔██║   ██║    ╚███╔╝
  ██║╚██╔╝██║   ██║    ██╔██╗
  ██║ ╚═╝ ██║   ██║   ██╔╝ ██╗
  ╚═╝     ╚═╝   ╚═╝   ╚═╝  ╚═╝
   MT5 Trade eXecutor · place, manage, and guard real trades
   ╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴

License: MIT Python 3.9+ MetaTrader 5 MCP Platform

Place, manage, and protect real MetaTrader 5 trades by talking to Claude — a Model Context Protocol (MCP) server that turns natural language into broker-validated order_send calls, with config-driven risk guardrails between you and a bad trade.

Requirements: Python 3.9+ · MetaTrader 5 (Windows, or Linux/macOS via Wine) · Claude Code

MTX is the execution sibling of MBT: MBT reads and backtests, MTX places and manages. Together they cover the whole loop — verify a strategy on real broker data, then let Claude execute it on a real (or demo) account, one confirmed trade at a time.

• Open, modify, and close positions — market orders, partial closes, SL/TP updates.
• Place and manage pending orders — buy_limit, sell_limit, buy_stop, sell_stop, with optional expiration.
• Risk-based position sizing — tell it a risk % or amount and a stop distance; it returns a broker-correct lot size.
• Money-management guardrails — max open positions, daily loss limits, equity stop, margin-level protection — enforced in code, not left to the model's judgement.
• Confirm-by-default — every write tool previews a broker order_check first and only trades when you say so (or when you explicitly opt into unattended auto mode).

---

MTX never guesses — the broker always has the final word

The #1 source of bugs in hand-rolled MT5 automation is code that recalculates or assumes broker constraints — a wrong filling mode, an unrounded lot size, a stop inside the freeze level. MTX doesn't guess any of that:

• Every price and volume is normalized against the symbol's own digits, volume_step, volume_min/max, and filling-mode bitmask, read fresh from symbol_info on every call.
• Every order runs through the broker's own order_check before anything is sent — MTX previews what the broker would do, not what it thinks the broker will do.
• Guardrail failures fail safe: if a risk check can't be evaluated, new trades are blocked rather than silently allowed through.

---

How it works

  You, in Claude Code                MTX (this server)
  ┌───────────────────────┐          ┌──────────────────────────────┐
  │ "buy 0.5 lots EURUSD,  │  calls   │ normalize price/volume        │
  │  sl 1.0950, tp 1.1100" ├──────────┤ pick_filling_mode              │
  └───────────────────────┘          │ mm.check_guardrails_block_new  │
                                      │ order_check  → preview         │
                                      │      │                         │
                                      │  confirm=true or mode: auto    │
                                      │      ▼                         │
                                      │ order_send → your MT5 terminal │
                                      └──────────────────────────────┘

In confirm mode (the default), every write tool returns a validated preview — balance, equity, margin impact, and the broker's order_check verdict — and only executes once you call it again with confirm=true. Flip execution.mode to auto in config.yaml for unattended use (a cron-driven mm_check heartbeat, or a hands-off Claude Desktop session), and every open still passes through the guardrails first.

---

Install

git clone https://github.com/FXDavid-OffbeatForex/MTX.git
cd MTX
pip install -r requirements.txt
cp config.example.yaml config.yaml

Edit config.yaml:

mt5_path: "C:/Path/To/Your/terminal64.exe"   # the terminal to trade on

# Most setups run MT5 already logged in — leave this out entirely in that case.
login:
  account:  null
  password: "${MTX_PASSWORD}"                # keep secrets in .env, never in config.yaml
  server:   null

execution:
  mode: confirm             # confirm | auto
  magic: 770077              # tags MTX's own orders
  deviation: 20               # max slippage, in points

mm:
  enforce: false             # false = mm_check only reports; true = it also closes
  max_open_positions: 5
  max_daily_loss_pct: 5.0
  min_margin_level_pct: 200.0
  equity_stop_pct: 20.0

Register the server with Claude Code:

claude mcp add MTX python "/abs/path/to/MTX/mcp_server.py"

Using Claude Desktop instead of Claude Code? Open Settings → Developer → Edit Config (this opens claude_desktop_config.json) and add:

{
  "mcpServers": {
    "mtx": {
      "command": "python",
      "args": ["/abs/path/to/MTX/mcp_server.py"]
    }
  }
}

Restart Claude Desktop to load it.

That's it — ping in a Claude Code session to confirm the terminal is reachable.

---

Money-management guardrails

Guardrails are deterministic, config-driven code — never left to model judgement:

Config key	What it does
max_open_positions	refuses new opens once you're at the cap
max_daily_loss_pct / max_daily_loss_money	halts new opens once today's realized + floating loss hits the limit
min_margin_level_pct	protective: flags/flattens when margin level drops too low
equity_stop_pct	protective: flattens everything if equity drops too far below balance
close_position_loss_pct / close_position_loss_money	protective: closes a single losing position past its limit

Opening actions check these before every send, in both confirm and auto mode. The protective side (mm_check) reports breaches by default; set mm.enforce: true and it also executes the closes — the setting a cron heartbeat flips on for unattended protection.

---

Tools (MCP)

Reads — safe, no confirmation needed:

Tool	Purpose
ping	check MT5 is running and reachable
get_config	active terminal, account, execution mode, mm summary (password redacted)
get_account_info	balance, equity, margin, margin level, leverage
get_symbol_info	digits, volume step, stops level, filling mode, live bid/ask
get_positions	open positions, optionally by symbol
get_pending_orders	working pending orders, optionally by symbol
get_history	closed deals over a date range
calc_position_size	risk-based lot sizing from a risk %/amount and stop distance
mm_check	evaluate guardrails; also acts if mm.enforce: true

Writes — gated by confirm / execution.mode:

Tool	Purpose
open_position	open a market position (buy/sell)
place_pending_order	place a buy_limit / sell_limit / buy_stop / sell_stop
modify_position	change SL/TP on an open position
modify_pending_order	change price/SL/TP/expiration on a pending order
close_position	close a position, in whole or in part
cancel_pending_order	cancel a working pending order

---

Examples

"What's my account balance and margin level?"
"Show me EURUSD's current spread and minimum stop distance."
"Size a position risking 1% of equity with a 200-point stop on GBPUSD."
"Buy 0.1 lots of XAUUSD with a stop at 2340 and target at 2380."
"Move the stop loss on ticket 65879650 to breakeven."
"Place a sell limit on USDJPY at 158.50, good till 2026-08-01."
"Check my guardrails — am I close to today's loss limit?"
"Close half my EURUSD position."

Every trading example above returns a preview first in the default confirm mode — Claude shows you the broker's own validation before anything executes.

---

Running on Linux / macOS (via Wine)

MetaTrader 5 and its Python package are Windows-only, but MTX runs fine on Linux and macOS through Wine — same approach as MBT:

1. Install MT5 under Wine (from your broker or MetaQuotes).
2. Install a Windows Python into that same Wine prefix and add MTX's dependencies:

   wine /path/to/wine/python.exe -m pip install MetaTrader5 PyYAML mcp
   

3. Point config.yaml at the Wine-mapped terminal path, and register the server with the Wine launcher:

   { "mcpServers": { "MTX": { "command": "wine", "args": ["/path/to/wine-python.exe", "/abs/path/to/MTX/mcp_server.py"] } } }
   

The MetaTrader5 Python package talks to the terminal through a Windows DLL, so it must run under the same Wine prefix's Python as the terminal — not your system Python.

---

Out of scope (for now)

OCO/bracket orders, server-side trailing stops, hedge-netting close_by, partial-fill auto-retry, and multi-account routing aren't implemented yet. The tool surface above is stable enough to add them later without breaking existing calls.

---

A note on risk

MTX will place real orders on whatever account config.yaml points at. Test on a demo account first. The confirm-by-default mode and the guardrails in core/mm.py exist so that no trade — and no runaway loss — happens without either your explicit approval or a limit you configured yourself. This software is provided as-is (see LICENSE) with no warranty; trading carries real financial risk, and past behavior is not a guarantee of future results.

---

Related

• MBT — MT5 Backtest Toolkit — the read/backtest sibling this project executes for.

Built on YouTube

This toolkit was built live on FX David — a series on building, verifying, and trading MT5 strategies with Claude AI.