mt5-trading-mcp 1.2.1

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 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.

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 (the MT5 terminal runs in an all-in-one Docker image; the agent talks MCP over HTTP) 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 an all-in-one Docker image (the agent talks MCP over HTTP). Full per-platform steps: docs/installation.md.
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 (recommended): bring up the Docker image — creds in deploy/.env, then docker compose -f deploy/docker-compose.yml up -d (it uses the published image; add --build only for local deploy/ changes). The server runs in the container and serves MCP over HTTP; the one-time VNC login + bridge alternative are in docs/installation.md.
3. Verify before doing anything else: Windows → python -m mt5_mcp doctor (expect the backend + [PASS] lines); Docker image → after the human's one-time VNC login, your first ping returns ok: true. Do not proceed if verification fails — report it to the human and stop.
4. Register / run the server: Docker image → it's already serving; register http://127.0.0.1:8765/mcp. Windows → python -m mt5_mcp serve (stdio) with a config under examples/clients/ (e.g. hermes.json) that scopes 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, if live account and using 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.