mt5-trading-mcp 1.2.0

Model Context Protocol server wrapping the MetaTrader 5 Python library.

mt5-mcp

Model Context Protocol server wrapping the MetaTrader 5 Python library — exposes a logged-in MT5 terminal as a set of MCP tools an AI agent can call.

⚠️ This software places real trades through your MetaTrader 5 terminal — real orders, real money, irreversible fills. Read DISCLAIMER.md and SECURITY.md before connecting it to a live account.

Status: v1.1.0 — first public release. Windows (native) or Linux (via Docker); Python 3.10+.

What it is

mt5-mcp lets an AI agent read your MetaTrader 5 account and place trades through it, over the Model Context Protocol. It runs locally, in the same process tree as your agent — no cloud, no telemetry.

• 11 read-only tools — account, quotes, positions, orders, history, OHLC bars, and broker-authoritative margin estimates. No consent gate.
• 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.

Full catalogue and the consent flow: docs/tools.md.

Quickstart (Windows, native)

pip install mt5-trading-mcp

1. Launch MetaTrader 5 and log into your broker. Enable AlgoTrading (toolbar button green).
2. Verify the terminal is reachable: python -m mt5_mcp doctor — expect [INFO] backend: native and [PASS] lines.
3. Run it: python -m mt5_mcp serve.

Linux (MT5 in Docker), the bridge backend, and wiring to an agent are in docs/installation.md.

For AI agents

If you are an AI agent and have been handed this repository to install and run, follow this procedure.

1. Detect the platform and pick a backend. Windows runs the MetaTrader5 library natively; Linux runs the terminal in Docker and connects over a bridge.
2. Install from this checkout:
   • Windows: pip install . (or uv sync --extra dev). Tell the human to launch MetaTrader 5, log into their broker, and enable AlgoTrading.
   • Linux: pip install '.[bridge]', then docker compose -f examples/docker-compose.yml up -d, have the human finish the MT5 install + broker login via KasmVNC at http://localhost:3000, and copy examples/config.toml.example to ~/.config/mt5-mcp/config.toml (keep the [mt5.bridge] block).
3. Verify before doing anything else: run python -m mt5_mcp doctor. Do not proceed unless it prints the active backend and [PASS] lines. If any check is [FAIL], report it to the human and stop.
4. Register / run the server: python -m mt5_mcp serve (stdio). To wire it into your own harness, use the matching config under examples/clients/ — e.g. hermes.json or openclaw.json — which scope you to the read-only tools by default.
5. Operate read-only unless explicitly asked to trade. The read tools are safe to call freely.
6. ⚠️ Hard rule — real money. place_order, modify_order, and close_position execute real, irreversible trades. When one returns an ApprovalPreview, show it verbatim to the human and only retry with approval_confirmed=true after they explicitly approve that specific order. Never auto-confirm, never batch-approve, never trade on a demo assumption — confirm it's a demo account first.

Tool semantics and the full consent flow: docs/tools.md. Under Claude Code, the skills in .claude/skills/ teach these directly.

Documentation

Guide	What's in it
Installation & setup	Requirements, Windows + Linux/Docker setup, wiring to an agent.
Configuration	config.toml schema, storage paths, hot-reload.
Tools & resources	Read tools, mutating tools + consent flow, subscribable resources.
MCP client setup	Per-client config snippets and Claude Code usage.
Transports & deployment	stdio/HTTP transports and Windows VPS patterns.
Contributing	How to contribute and run the tests.
Changelog	Release history and known limitations.

Safety

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.

Mutating actions above the configured auto_approve_notional (or that widen stops) require explicit human approval via the ApprovalPreview flow. Every mutating call is recorded in an append-only audit JSONL log. 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. On top of it: the MCP tools (src/mt5_mcp/tools/), subscribable resources (src/mt5_mcp/resources/), the consent / idempotency / audit layer (src/mt5_mcp/policy/), and the change-detection streaming subsystem (src/mt5_mcp/streaming/). The Pydantic models in src/mt5_mcp/types.py and src/mt5_mcp/config.py are the source of truth for the data and config schemas.

Contributing

Contributions are welcome — see CONTRIBUTING.md for the dev setup, test workflow, and project principles.

License

MIT — see LICENSE.