{
  "markdown": "# MetaTrader 5 MCP Bridge\n\n<!-- mcp-name: io.github.vincentwongso/mt5-trading-mcp -->\n\n**Let an AI agent manage your MetaTrader 5 account over [Model Context Protocol](https://modelcontextprotocol.io) - with configurable human approval gate.**\n\n[![PyPI version](https://img.shields.io/pypi/v/mt5-trading-mcp.svg)](https://pypi.org/project/mt5-trading-mcp/)\n[![PyPI downloads](https://static.pepy.tech/badge/mt5-trading-mcp/month)](https://pepy.tech/project/mt5-trading-mcp)\n[![Python](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://pypi.org/project/mt5-trading-mcp/)\n[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](https://github.com/vincentwongso/mt5-trading-mcp/blob/main/LICENSE)\n[![Tests](https://img.shields.io/github/actions/workflow/status/vincentwongso/mt5-trading-mcp/test.yml?branch=main&label=tests)](https://github.com/vincentwongso/mt5-trading-mcp/actions/workflows/test.yml)\n[![GitHub stars](https://img.shields.io/github/stars/vincentwongso/mt5-trading-mcp?style=flat&label=stars)](https://github.com/vincentwongso/mt5-trading-mcp/stargazers)\n[![MCP](https://img.shields.io/badge/MCP-server-blue.svg)](https://modelcontextprotocol.io)\n[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)\n\n<p align=\"center\">\n  <img src=\"https://raw.githubusercontent.com/vincentwongso/mt5-trading-mcp/main/demo/mt5-mcp-demo.gif\" width=\"600\" alt=\"mt5-mcp demo: an AI agent places and closes a live trade over MCP\"><br>\n  <sub>A <a href=\"https://github.com/NousResearch\">Hermes</a> agent placing then closing a real 0.01-lot trade on a <b>demo</b> account, end-to-end over MCP on Linux.</sub>\n</p>\n\n<p align=\"center\">\n  <img src=\"https://raw.githubusercontent.com/vincentwongso/mt5-trading-mcp/main/demo/mt5-history.png\" width=\"820\" alt=\"The same round-trip in MetaTrader 5's History tab\"><br>\n  <sub>Not a mock-up - the same round-trip in MetaTrader 5's own History tab; the tickets and balance match the recording.</sub>\n</p>\n\n> ⚠️ **This software places _real_ trades through your MetaTrader 5 terminal with\n> real orders and irreversible fills.** Read\n> [DISCLAIMER.md](https://github.com/vincentwongso/mt5-trading-mcp/blob/main/DISCLAIMER.md)\n> and [SECURITY.md](https://github.com/vincentwongso/mt5-trading-mcp/blob/main/SECURITY.md)\n> before connecting it to a live account. Always test using your demo account first.\n\nRuns locally - in the same process tree as your agent, no cloud, no telemetry.\nWindows (native) or Linux (via Docker); Python 3.10+.\n\n> 📖 **The story behind this:** this project is built step by step in\n> [*Wiring AI agent into MetaTrader 5*](https://engineering.fintrixmarkets.com/posts/mt5-mcp-part-1/),\n> Part 1 of the *Trade with AI agent* series on the Fintrix engineering blog.\n\n## What it is\n\n`mt5-mcp` lets an AI agent read your MetaTrader 5 account and place trades\nthrough it, over the Model Context Protocol.\n\n- **12 read-only tools**: account, quotes, positions, orders, history, OHLC\n  bars, broker-authoritative margin estimates, and native chart screenshots\n  (Windows). No consent gate.\n- **4 mutating tools**: `place_order`, `modify_order`, `cancel_order`,\n  `close_position`, each behind a preflight + human-consent + idempotency +\n  audit layer.\n- **3 subscribable resources**: live `account://`, `positions://`, and\n  `quotes://{symbol}` snapshots that push change notifications.\n- **2 ready-to-use Claude Code skills** ship in\n  [`.claude/skills/`](https://github.com/vincentwongso/mt5-trading-mcp/tree/main/.claude/skills):\n  `mt5-market-data` and `mt5-trading` teach an agent how to read the account and\n  run the consent flow safely.\n\nFull catalogue and the consent flow: **[docs/tools.md](https://github.com/vincentwongso/mt5-trading-mcp/blob/main/docs/tools.md)**.\n\n## Why mt5-mcp\n\n- **A safety layer, not just an API wrapper.** Every mutating call routes through\n  preflight checks -> an opt-in human-consent gate (arm it to require approval) ->\n  idempotency -> an append-only audit log, so you can put a human in the loop on\n  trades and always keep a replayable record of what the agent did.\n- **An honest threat model.** It treats an LLM wired to `place_order` as a live\n  attack surface and says so plainly - the MCP is explicitly *not* the security\n  boundary (see [SECURITY.md](https://github.com/vincentwongso/mt5-trading-mcp/blob/main/SECURITY.md)).\n- **Verifiable proof, not a mock-up.** The demo above is a real round-trip; the\n  tickets and balance match MetaTrader 5's own History tab.\n- **Local-first.** No cloud, no telemetry; runs beside your agent. Windows-native\n  or Linux via an all-in-one Docker image (no `rpyc` version-matching).\n\n## Quickstart (Windows, native)\n\n```bash\npip install mt5-trading-mcp\n```\n\n1. Launch MetaTrader 5 and log into your broker. Enable **AlgoTrading** (toolbar\n   button green).\n2. Verify the terminal is reachable: `python -m mt5_mcp doctor`: expect\n   `[INFO] backend: native` and `[PASS]` lines.\n3. Run it: `python -m mt5_mcp serve`.\n\nWire it to OpenClaw in one command (registers the `mcp.servers` entry):\n\n```bash\nopenclaw mcp set mt5-mcp '{\"command\":\"python\",\"args\":[\"-m\",\"mt5_mcp\",\"serve\"]}'\n```\n\n## Quickstart (Linux, Docker)\n\nThe MT5 terminal + the MCP run headless in an all-in-one image; your agent talks\nMCP over HTTP. No host Python, no bridge.\n\n```bash\ncp deploy/.env.example deploy/.env   # add MT5_LOGIN / MT5_PASSWORD / MT5_SERVER\ndocker compose -f deploy/docker-compose.yml up -d\n```\n\nLog the terminal in once via the KasmVNC web UI at `http://127.0.0.1:3001`\n(**File -> Login to Trade Account**; persists across restarts), then point your\nagent at `http://127.0.0.1:8765/mcp`. Wire it to OpenClaw in one command:\n\n```bash\nopenclaw mcp set mt5-mcp '{\"url\":\"http://127.0.0.1:8765/mcp\",\"transport\":\"streamable-http\"}'\n```\n\nFull walkthrough:\n**[docs/installation.md](https://github.com/vincentwongso/mt5-trading-mcp/blob/main/docs/installation.md)**.\n\n## Chart screenshots (Windows only)\n\n`get_chart_screenshot(symbol, timeframe, annotations?)` returns a PNG of the\nnative MT5 chart, optionally annotated, so an LLM can read it visually\n(candles, support/resistance, patterns). Because the MetaTrader5 Python API\ncannot capture charts, this uses a small MQL5 Expert Advisor that runs inside\na GUI terminal and calls `ChartScreenShot()`.\n\nSee [Chart annotations](docs/tools.md#chart-annotations) for marking up\nsupport/resistance lines, trendlines and notes before capture.\n\nSetup (one time):\n\n1. Install and attach the `AgentScreenshot` EA - see `mql5/README.md`.\n2. Optionally set a template so your indicators/drawings appear in the shot:\n   `[screenshot]` `template = \"agent.tpl\"` in your config, or leave it unset\n   for the default chart.\n\nConfig knobs (`[screenshot]` section): `width` (default 1600), `height`\n(default 900), `template` (default none), `timeout_s` (default 10).\n\nNot available on the headless Linux/Docker deployment: it needs a GUI\nterminal. Off Windows the tool returns `SCREENSHOT_NOT_SUPPORTED`.\n\n## For AI agents\n\n**If you've been handed this repository to install and run, follow the runbook\nin [docs/agents.md](https://github.com/vincentwongso/mt5-trading-mcp/blob/main/docs/agents.md).**\nIt covers platform detection, install, verification, registering the server, and\nthe hard safety rules for trades - read it before calling any mutating tool.\n\n## Documentation\n\n| Guide | What's in it |\n|---|---|\n| [Installation & setup](https://github.com/vincentwongso/mt5-trading-mcp/blob/main/docs/installation.md) | Requirements, Windows + Linux/Docker setup, wiring to an agent. |\n| [For AI agents](https://github.com/vincentwongso/mt5-trading-mcp/blob/main/docs/agents.md) | Step-by-step runbook for an agent installing and running the server. |\n| [Configuration](https://github.com/vincentwongso/mt5-trading-mcp/blob/main/docs/configuration.md) | `config.toml` schema, storage paths, hot-reload. |\n| [Tools & resources](https://github.com/vincentwongso/mt5-trading-mcp/blob/main/docs/tools.md) | Read tools, mutating tools + consent flow, subscribable resources. |\n| [MCP client setup](https://github.com/vincentwongso/mt5-trading-mcp/blob/main/docs/clients.md) | Per-client config snippets and Claude Code usage. |\n| [Transports & deployment](https://github.com/vincentwongso/mt5-trading-mcp/blob/main/docs/deployment.md) | stdio/HTTP transports and Windows VPS patterns. |\n| [Contributing](https://github.com/vincentwongso/mt5-trading-mcp/blob/main/CONTRIBUTING.md) | How to contribute and run the tests. |\n| [Changelog](https://github.com/vincentwongso/mt5-trading-mcp/blob/main/CHANGELOG.md) | Release history and known limitations. |\n\n## Safety\n\n`mt5-mcp` is **not** the security boundary, the broker's MT5 server enforces\nthe hard limits (margin, max-lot, symbol permissions). Pre-flight checks in the\npolicy engine are UX guardrails to catch agent mistakes early, not security\ncontrols.\n\nThe human-consent gate is **opt-in and off by default**: `auto_approve_notional`\ndefaults to `0`, so mutating calls auto-execute (full-open) - intended for trusted\nor unattended agents. **Arm the gate by setting `auto_approve_notional` > 0**:\norders/closes whose notional is at or above it then return an `ApprovalPreview`\nyou must confirm, and modifying a stop to widen or remove it also requires\napproval. The pre-flight limits (`max_*`) and symbol allow/deny lists are likewise\nopt-in (`0` / empty = off). Every mutating call is recorded in an append-only audit\nJSONL log regardless. For vulnerability disclosure, see\n[SECURITY.md](https://github.com/vincentwongso/mt5-trading-mcp/blob/main/SECURITY.md).\n\n## Architecture\n\n`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.\n\n```\n     Agent / MCP client  (Hermes, OpenClaw, Claude Code, Claude Desktop, …)\n                               │\n                               │   stdio  ·  loopback HTTP\n                               ▼\n ┌──────────────────────────────────────────────────────────┐\n │                      FastMCP server                      │\n │                                                          │\n │   tools/        resources/        policy/                │\n │   read +        subscribable      consent · idempotency  │\n │   mutating      account/quotes    · audit (JSONL)        │\n │                                                          │\n │   streaming/  - change-detection poller + dispatcher     │\n │   types.py · config.py - Pydantic schemas: source of     │\n │                          truth for data + config         │\n │                                                          │\n └──────────────────────────────────────────────────────────┘\n                               │\n                               ▼\n ┌──────────────────────────────────────────────────────────┐\n │                                                          │\n │   adapter/  MT5Client                                    │\n │   one terminal connection · broker-TZ inference ·        │\n │   type conversions · transparent reinit                  │\n │                                                          │\n └──────────────────────────────────────────────────────────┘\n                               │\n                               ▼\nMetaTrader 5 Python library  ->  broker terminal  ->  broker server\n```\n\nThe module paths shown (`tools/`, `resources/`, `policy/`, `streaming/`,\n`adapter/`, `types.py`, `config.py`) all live under `src/mt5_mcp/`.\n\n## Contributing\n\nContributions are welcome, see\n[CONTRIBUTING.md](https://github.com/vincentwongso/mt5-trading-mcp/blob/main/CONTRIBUTING.md)\nfor the dev setup, test workflow, and project principles.\n\n## License\n\nMIT - see [`LICENSE`](https://github.com/vincentwongso/mt5-trading-mcp/blob/main/LICENSE).\n",
  "bytes": 12099,
  "sha": "ce430e1ed47bcd68b650b6cf7c555100617b69523bcb0b21656934e90206353b",
  "repo_slug": "vincentwongso/mt5-trading-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_vincentwongso_mt5_trading_mcp_57b32ae8/readme"
}