Mt5 Trading Mcp

MetaTrader 5 MCP Bridge

Let an AI agent manage your MetaTrader 5 account over Model Context Protocol - with configurable human approval gate.

[](https://pypi.org/project/mt5-trading-mcp/) [](https://pepy.tech/project/mt5-trading-mcp) [](https://pypi.org/project/mt5-trading-mcp/) [](https://github.com/vincentwongso/mt5-trading-mcp/blob/main/LICENSE) [](https://github.com/vincentwongso/mt5-trading-mcp/actions/workflows/test.yml) [](https://github.com/vincentwongso/mt5-trading-mcp/stargazers) [](https://modelcontextprotocol.io) [](https://github.com/astral-sh/ruff)

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.

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

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

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

Why mt5-mcp

• 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)

pip install mt5-trading-mcp

1. Launch MetaTrader 5 and log into your broker. Enable AlgoTrading (toolbar

button green).

1. Verify the terminal is reachable: python -m mt5_mcp doctor: expect

[INFO] backend: native and [PASS] lines.

1. Run it: python -m mt5_mcp serve.

Wire it to OpenClaw in one command (registers the mcp.servers entry):

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.

cp deploy/.env.example deploy/.env   # add MT5_LOGIN / MT5_PASSWORD / MT5_SERVER
docker compose -f deploy/docker-compose.yml up -d

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:

openclaw mcp set mt5-mcp '{"url":"http://127.0.0.1:8765/mcp","transport":"streamable-http"}'

Full walkthrough: docs/installation.md.

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.

Documentation

| Guide | What's in it | |---|---| | Installation & setup | Requirements, Windows + Linux/Docker setup, wiring to an agent. | | For AI agents | Step-by-step runbook for an agent installing and running the server. | | 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.

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.

     Agent / MCP client  (Hermes, OpenClaw, Claude Code, Claude Desktop, …)
                               │
                               │   stdio  ·  loopback HTTP
                               ▼
 ┌──────────────────────────────────────────────────────────┐
 │                      FastMCP server                      │
 │                                                          │
 │   tools/        resources/        policy/                │
 │   read +        subscribable      consent · idempotency  │
 │   mutating      account/quotes    · audit (JSONL)        │
 │                                                          │
 │   streaming/  - change-detection poller + dispatcher     │
 │   types.py · config.py - Pydantic schemas: source of     │
 │                          truth for data + config         │
 │                                                          │
 └──────────────────────────────────────────────────────────┘
                               │
                               ▼
 ┌──────────────────────────────────────────────────────────┐
 │                                                          │
 │   adapter/  MT5Client                                    │
 │   one terminal connection · broker-TZ inference ·        │
 │   type conversions · transparent reinit                  │
 │                                                          │
 └──────────────────────────────────────────────────────────┘
                               │
                               ▼
MetaTrader 5 Python library  ->  broker terminal  ->  broker server

The module paths shown (tools/, resources/, policy/, streaming/, adapter/, types.py, config.py) all live under src/mt5_mcp/.

Contributing

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

License

MIT - see LICENSE.

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: vincentwongso
• Source: vincentwongso/mt5-trading-mcp
• License: MIT
• Homepage: https://engineering.fintrixmarkets.com

Install and usage instructions live in the source repository linked above.