mt5-mcp

mt5-mcp is an MCP server so AI agents can inspect and trade against a MetaTrader 5 terminal — account, symbols, quotes, orders/positions, history — with a full offline mock for CI and demos.

---

Modes

Mode	When	Behavior
mock (default)	Windows / CI / no terminal	Seeded demo account, FX/CFD symbols, orders, history
live	Host has a bridge configured	Optional file/HTTP bridge (see env vars); fails closed if unavailable

---

Highlights

Capability	Description
Offline demo	mt5-mcp demo exercises doctor, quotes, market order, history
MCP stdio serve	Plug into Cursor / Claude / Grok as an MCP server
One-shot call	mt5-mcp call … without a full MCP host
Safety	Mock never talks to a real broker; live needs explicit env

---

Quick start

cd mt5-mcp
python -m venv .venv
.\.venv\Scripts\activate
pip install -e ".[dev]"

mt5-mcp version
mt5-mcp demo
mt5-mcp tools list
pytest -q

Mock mode needs no MetaTrader install.

---

CLI reference

Command	Purpose
mt5-mcp version	Version + mode
mt5-mcp status	Mode, balance, equity, positions, orders
mt5-mcp demo	Offline smoke of core backend APIs
mt5-mcp doctor	Backend health
mt5-mcp serve	MCP server over stdio
mt5-mcp call …	One-shot tool call
mt5-mcp tools list	List MCP tools

mt5-mcp serve

---

MCP tools

Tool	Purpose
mt5_mode	Get/set mock|live
mt5_doctor	Connectivity / account health
mt5_seed_demo	Reset mock account
mt5_account	Balance, equity, margin, trade mode
mt5_symbols	Symbol list
mt5_quote	Bid/ask / last
mt5_positions	Open positions (filled market orders)
mt5_orders	Pending orders (limit/stop, not yet filled)
mt5_order_send	Market/pending
mt5_position_close	Close position by ticket
mt5_history_deals	Deal history
mt5://account (resource)	Account + positions snapshot

---

MCP host config

{
  "mcpServers": {
    "mt5-mcp": {
      "command": "python",
      "args": ["-m", "mt5_mcp"],
      "env": {
        "MT5_MCP_MODE": "mock"
      }
    }
  }
}

Also see examples/cursor_mcp.json.

---

Live bridge (optional)

Set env (never commit secrets):

Variable	Meaning
MT5_MCP_MODE	mock or live
MT5_MCP_MAGIC	Optional magic number for live orders
MT5_MCP_MAX_VOLUME	Max order volume cap
MT5_MCP_SYMBOL_ALLOWLIST	Comma-sep allowlisted symbols
MT5_MCP_BRIDGE_URL	Optional HTTP bridge base URL
MT5_MCP_BRIDGE_FILE	Optional request/response JSON file path

Without a working bridge, live mode returns structured errors; demos stay on mock.

---

Safety

Rule	Detail
Mock-only env	Copy examples/env.mock.example → .env and keep MT5_MCP_MODE=mock
No secrets in git	Add .env to .gitignore — never commit live broker credentials
Max volume	Set MT5_MCP_MAX_VOLUME to cap any single order in live mode
Symbol allowlist	Restrict tradeable symbols via MT5_MCP_SYMBOL_ALLOWLIST (comma-sep)

---

Deal history

Deal history fields

Field	Type	Description
ticket	int	Deal ID
time	str	Timestamp
symbol	str	Instrument
type	str	Deal type (buy/sell)
volume	float	Lot size
price	float	Execution price
commission	float	Broker commission (mock)
swap	float	Overnight swap (mock)
profit	float	Net P&L (mock)

---

Development

pip install -e ".[dev]"
ruff check src tests
pytest -q
mt5-mcp demo

---

License

MIT