Let an AI agent read and trade a MetaTrader 5 account over MCP, behind a human-approval gate.
This MCP server lets an AI agent read and trade a MetaTrader 5 account over the Model Context Protocol. It includes a configurable human-approval gate for managing actions. The implementation is published as a Python package and is described as a “MetaTrader 5 MCP Bridge.”
🛠️ Key Features
MetaTrader 5 account access for reading and trading
Let an AI agent manage your MetaTrader 5 account over Model Context Protocol - with configurable human approval gate.
mt5-mcp demo: an AI agent places and closes a live trade over MCP A Hermes agent placing then closing a real 0.01-lot trade on a demo account, end-to-end over MCP on Linux.
Not a mock-up - the same round-trip in MetaTrader 5's own History tab; the tickets and balance match the recording.
⚠️ This software places real trades through your MetaTrader 5 terminal with
real orders and irreversible fills. Read
DISCLAIMER.md
and SECURITY.md
before connecting it to a live account. Always test using your demo account first.
Runs locally - in the same process tree as your agent, no cloud, no telemetry.
Windows (native) or Linux (via Docker); Python 3.10+.
📖 The story behind this: this project is built step by step in
Wiring AI agent into MetaTrader 5,
Part 1 of the Trade with AI agent series on the Fintrix engineering blog.
What it is
mt5-mcp lets an AI agent read your MetaTrader 5 account and place trades
through it, over the Model Context Protocol.
4 mutating tools: place_order, modify_order, cancel_order,
close_position, each behind a preflight + human-consent + idempotency +
audit layer.
3 subscribable resources: live account://, positions://, and
quotes://{symbol} snapshots that push change notifications.
2 ready-to-use Claude Code skills ship in
.claude/skills/:
mt5-market-data and mt5-trading teach an agent how to read the account and
run the consent flow safely.
A safety layer, not just an API wrapper. Every mutating call routes through
preflight checks -> an opt-in human-consent gate (arm it to require approval) ->
idempotency -> an append-only audit log, so you can put a human in the loop on
trades and always keep a replayable record of what the agent did.
An honest threat model. It treats an LLM wired to place_order as a live
attack surface and says so plainly - the MCP is explicitly not the security
boundary (see SECURITY.md).
Verifiable proof, not a mock-up. The demo above is a real round-trip; the
tickets and balance match MetaTrader 5's own History tab.
Local-first. No cloud, no telemetry; runs beside your agent. Windows-native
or Linux via an all-in-one Docker image (no rpyc version-matching).
Quickstart (Windows, native)
bash
pip install mt5-trading-mcp
Launch MetaTrader 5 and log into your broker. Enable AlgoTrading (toolbar
button green).
Verify the terminal is reachable: python -m mt5_mcp doctor: expect
[INFO] backend: native and [PASS] lines.
Run it: python -m mt5_mcp serve.
Wire it to OpenClaw in one command (registers the mcp.servers entry):
bash
openclaw mcp set mt5-mcp '{"command":"python","args":["-m","mt5_mcp","serve"]}'
Quickstart (Linux, Docker)
The MT5 terminal + the MCP run headless in an all-in-one image; your agent talks
MCP over HTTP. No host Python, no bridge.
Log the terminal in once via the KasmVNC web UI at http://127.0.0.1:3001
(File -> Login to Trade Account; persists across restarts), then point your
agent at http://127.0.0.1:8765/mcp. Wire it to OpenClaw in one command:
bash
openclaw mcp set mt5-mcp '{"url":"http://127.0.0.1:8765/mcp","transport":"streamable-http"}'
get_chart_screenshot(symbol, timeframe, annotations?) returns a PNG of the
native MT5 chart, optionally annotated, so an LLM can read it visually
(candles, support/resistance, patterns). Because the MetaTrader5 Python API
cannot capture charts, this uses a small MQL5 Expert Advisor that runs inside
a GUI terminal and calls ChartScreenShot().
See Chart annotations for marking up
support/resistance lines, trendlines and notes before capture.
Setup (one time):
Install and attach the AgentScreenshot EA - see mql5/README.md.
Optionally set a template so your indicators/drawings appear in the shot:
[screenshot]template = "agent.tpl" in your config, or leave it unset
for the default chart.
Not available on the headless Linux/Docker deployment: it needs a GUI
terminal. Off Windows the tool returns SCREENSHOT_NOT_SUPPORTED.
For AI agents
If you've been handed this repository to install and run, follow the runbook
in docs/agents.md.
It covers platform detection, install, verification, registering the server, and
the hard safety rules for trades - read it before calling any mutating tool.
mt5-mcp is not the security boundary, the broker's MT5 server enforces
the hard limits (margin, max-lot, symbol permissions). Pre-flight checks in the
policy engine are UX guardrails to catch agent mistakes early, not security
controls.
The human-consent gate is opt-in and off by default: auto_approve_notional
defaults to 0, so mutating calls auto-execute (full-open) - intended for trusted
or unattended agents. Arm the gate by setting auto_approve_notional > 0:
orders/closes whose notional is at or above it then return an ApprovalPreview
you must confirm, and modifying a stop to widen or remove it also requires
approval. The pre-flight limits (max_*) and symbol allow/deny lists are likewise
opt-in (0 / empty = off). Every mutating call is recorded in an append-only audit
JSONL log regardless. For vulnerability disclosure, see
SECURITY.md.
Architecture
mt5-mcp wraps the MetaTrader 5 Python library behind a FastMCP server. A single MT5Client (src/mt5_mcp/adapter/) owns the terminal connection, broker-timezone inference, and type conversions; everything else sits on top of it. The Pydantic models in src/mt5_mcp/types.py / src/mt5_mcp/config.py are the source of truth for the data and config schemas.
