MetaTrader 5 MCP
An MCP server for MCP Studio (or any MCP-compatible host) that lets an agent trade through a MetaTrader 5 terminal. Position sizing is computed from account balance, stop distance, and a risk percent — so the natural way to ask is the way it works:
"Place a 1:4 market buy in EURUSD with a 10 pip stop loss and risk 1% of the account."
The agent calls place_risk_order(symbol="EURUSD", side="buy", stop_loss_pips=10, risk_reward_ratio=4, risk_percent=1). The MCP reads the live balance + symbol pricing, computes lot size so a stop-out loses exactly 1% of balance, sets the take profit at 4× the stop distance, and submits the order.
⚠️ This MCP can place real trades on your real broker account. Test against a demo account first. Use
dry_run: truewhen wiring up new prompts. The authors are not responsible for losses caused by misuse, broker quirks, or unexpected agent behavior. Read the Safety section before using it on a live account.
Tools
| Tool | What it does |
|---|---|
account_info() |
Balance, equity, margin, leverage. |
symbol_info(symbol) |
digits, point, tick_size, tick_value, contract_size, volume bounds, bid, ask. |
get_positions(symbol?) |
List open positions, optionally filtered. |
place_market_order(symbol, side, volume, sl?, tp?, comment?) |
Direct market order with an explicit lot size. |
place_risk_order(symbol, side, stop_loss_pips, risk_reward_ratio, risk_percent, dry_run?) |
The high-level entry. Computes lots so SL = risk_percent of balance, sets TP at risk_reward_ratio × SL distance. dry_run: true returns the plan without placing the order. |
close_position(ticket) |
Close by ticket. |
modify_position(ticket, sl?, tp?) |
Update SL/TP on an open position. |
Quick commands
| Trigger | Action |
|---|---|
/mt5_account |
Show balance, equity, and margin. |
/mt5_positions |
List open positions on the default symbol. |
/mt5_plan |
Dry-run a 1:2 buy on the default symbol, 10-pip SL, default risk %. |
The "default symbol" and "default risk percent" are stored per-MCP and editable in Studio's MCP settings (default: EURUSD, 1%).
How it works
agent ──MCP stdio──▶ Node TS server ──stdin/stdout JSON──▶ Python (MetaTrader5 lib) ──▶ MT5 terminal
- Node owns the MCP protocol surface and risk math (testable in vitest).
- Python owns terminal I/O via the official
MetaTrader5package. - The Python child is long-lived: spawned once on MCP startup, kept alive for the session, and shut down on SIGINT/SIGTERM.
Prerequisites
You need an MT5 terminal and a Python interpreter that can import MetaTrader5. The MetaTrader5 Python package is Windows-only — it loads the terminal's DLLs directly.
- Windows: install MT5, then
pip install MetaTrader5. Done. - macOS / Linux: run MT5 inside Wine (PlayOnMac, CrossOver, etc.) and install
MetaTrader5into the Wine prefix's Python. SetMT5_PYTHONto that interpreter path.
If the terminal is already logged in, you don't need to pass credentials — the MCP attaches to the running session. If it isn't, supply MT5_LOGIN, MT5_PASSWORD, MT5_SERVER (the manifest collects these securely).
Install in MCP Studio
From the MCP Studio prompt panel:
/install https://github.com/RPieterse/mcp-studio-mt5-mcp
…or install from a local clone:
/install /path/to/mcp-studio-mt5-mcp
Studio will prompt for:
- Python interpreter — e.g.
/usr/local/bin/python3(or your Wine-prefix python on macOS). - Terminal path (optional) — path to
terminal64.exeif you have multiple MT5 installs. - Login / password / server (optional) — only if the terminal isn't already logged in.
Then say "show my MT5 balance" or "place a 1:3 buy on USDJPY with a 20 pip stop, risk 0.5%".
Position sizing — what the math actually does
place_risk_order runs this on every call:
pip_size = 0.0001 for 5-digit forex, 0.01 for 3-digit JPY, 10 × point otherwise
sl_distance = stop_loss_pips × pip_size
loss_per_lot = (sl_distance / tick_size) × tick_value // account-currency PnL per 1.0 lot
risk_amount = balance × (risk_percent / 100)
raw_volume = risk_amount / loss_per_lot
volume = round_down_to(volume_step, clamp to [volume_min, volume_max])
tp_distance = sl_distance × risk_reward_ratio
entry = ask (buy) | bid (sell)
sl = entry − sl_distance (buy) | entry + sl_distance (sell)
tp = entry + tp_distance (buy) | entry − tp_distance (sell)
tick_value comes from the live symbol_info, so it handles cross-currency conversion correctly (XAUUSD, USDJPY in a EUR account, etc.) as long as the broker reports it accurately.
Local development
npm install
npm run build
npm test
The vitest suite covers the risk math and tool dispatch against a mock Mt5Api — no terminal needed. To iterate live against MT5 Studio:
npx tsc --watch
Safety
- Every
place_risk_orderacceptsdry_run: true. Use it when wiring up new prompts. - The MCP refuses to submit if the computed volume after rounding is ≤ 0 (e.g. stop too tight or balance too low).
- Stops and targets are sent with the order, not after — so a network blip between order and SL set can't leave an unprotected position.
Permissions declared
secrets: mt5_credentials
No filesystem or network sandbox declared — the Python child talks to MT5 over the terminal's local IPC and (when not pre-attached) to the broker's MT5 server over the broker's protocol.
License
MIT.
