mt5-mcp

MetaTrader 5 automation today means bouncing between the terminal, MetaEditor, the file explorer, and the Strategy Tester by hand. mt5-mcp puts all of that behind one MCP server so an AI agent can read your account, write and compile MQL5 code, sync a local workspace with your MT5 data folder, and analyze backtests — as a normal part of a coding session, with everything it does audited for you to review afterwards.

Claude connects over stdio; ChatGPT connects over Streamable HTTP at a /mcp endpoint. Both drive the same engine, with the same safety gates — so when Claude is unavailable, ChatGPT can pick up the exact same workflow.

Quick start

Requires Python 3.11+.

git clone https://github.com/alikhande70/Mt5_mcp.git
cd Mt5_mcp
python3 -m venv .venv
source .venv/bin/activate          # Windows: .venv\Scripts\Activate.ps1
pip install -e ".[dev]"

# Claude (stdio) — the default:
mt5-mcp

# ChatGPT (HTTP /mcp) — full parity, token required:
MT5_MCP_PROFILE=chatgpt_full \
MT5_MCP_TRANSPORT=streamable-http \
MT5_MCP_HTTP_TOKEN="$(openssl rand -hex 24)" \
mt5-mcp

The full suite runs without MetaTrader5 installed, so you can develop and test the toolkit on any platform. Real MT5 tools activate on Windows where the terminal lives. See Setup & configuration for details.

Architecture overview

There is exactly one engine: tool_registry.py (what tools exist), action_router.py (audit → execute), and the mt5_mcp.*_tools domain modules (the actual MT5 / filesystem logic). Claude and ChatGPT are two doors into that same engine — nothing is duplicated or forked per client. A single module, mt5_bridge.py, is the only file that imports the MetaTrader5 package, which is why everything else — including the entire test suite — runs anywhere.

Every dispatched tool call is appended to logs/audit.jsonl before and after it runs, so there is always a record of what happened. See docs/ARCHITECTURE.md for the module-by-module breakdown.

What it can do

70 MCP tools across the whole MetaTrader 5 workflow:

• Read & inspect — account/balance/margin, symbols, ticks and OHLC candles, open positions, orders, and trade history.

• MQL5 development — read, search, diff, write, update, and generate Experts / indicators / scripts (every overwrite and delete is backed up first), then compile with the MetaEditor CLI.

• Strategy Tester — discover, import, parse, and compare_backtests on Strategy Tester reports (net profit, drawdown, profit factor, recovery factor, win rate, and more).

• Workspace — snapshot/restore/clean a local workspace and sync it both ways with the MT5 MQL5 folder.

• Trading — pure-Python position sizing / risk math, order planning and validation, demo-only order submission, and consent-gated live execution.

Every tool works — or fails with a clear message — even when MetaTrader5 isn't installed, MT5 isn't running, or MetaEditor can't be found. Full reference: docs/TOOLS.md.

Profiles

The active tool set is chosen by MT5_MCP_PROFILE:

resolve_profile_specs("chatgpt_full") returns the identical tool list as full — parity is deliberate, not a filtered subset. chatgpt_safe is the one profile that actually narrows the door, via an explicit allowlist. Full details: docs/CHATGPT_MCP.md.

Workflow

A typical development loop drives the tools end to end: inspect an EA or files, analyze them, apply approved changes (backed up on write), compile, run a backtest, inspect the report, and compare backtests — then iterate. The same loop is available to Claude and to ChatGPT under chatgpt_full. See docs/BACKTEST_WORKFLOW.md and docs/COMMAND_PLAYBOOK.md.

Safety model

The principle is audit everything, block what matters — defense in depth, not a reflexive permission prompt on every call:

• Transport perimeter — the HTTP transports require a bearer token (MT5_MCP_HTTP_TOKEN) checked in constant time, and fail closed: with no token set, the server refuses to start rather than listen unauthenticated.

• File & path guards — every user-supplied path is confined to the workspace or the detected MQL5 folder (no traversal escape), and every overwrite or delete is backed up first.

• Trading guards — order_send_demo_only runs only on a confirmed demo account (ambiguity fails closed), and the only tool call that can be refused anywhere in the project — real-money execution — passes through the live-trade consent gate: a short-lived consent record, an exact order-hash match, and a human confirmation phrase, all before mt5_bridge.order_send is ever reached.

See docs/ACCESS_MODEL.md for the reasoning and docs/LIVE_TRADING_CONSENT.md for the exact consent flow.

Setup & configuration

Installation

Use a virtual environment — many Linux distros (and any "externally managed" Python) refuse a bare pip install -e ".[dev]" outside one.

• pip install -e . — core server, works anywhere, no MT5 required.

• pip install -e ".[mt5]" — adds the MetaTrader5 package (Windows only).

• pip install -e ".[process]" — adds psutil for process tools.

• pip install -e ".[dev]" — everything above plus pytest / ruff for development.

This registers the mt5-mcp console command.

Windows quickstart

See docs/QUICKSTART_WINDOWS.md for the full walkthrough. The short version:

git clone https://github.com/alikhande70/Mt5_mcp.git
cd Mt5_mcp
python -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install -e ".[dev]"
copy .env.example .env
python scripts\mt5_readiness_check.py

MT5 & environment variables

mt5-mcp auto-detects the terminal, data folder, and MetaEditor from common Windows install locations, or you can set them explicitly in .env (see .env.example). Run mt5_readiness_check (or python scripts/mt5_readiness_check.py) any time to see exactly what was detected and what's missing.

Claude usage

Copy examples/claude_desktop_config.example.json into your Claude Desktop claude_desktop_config.json, adjusting the env paths for your machine:

{
  "mcpServers": {
    "mt5-mcp": {
      "command": "mt5-mcp",
      "env": { "MT5_TERMINAL_PATH": "C:\\Program Files\\MetaTrader 5\\terminal64.exe" }
    }
  }
}

For Claude Code, add the server the same way via examples/claude_code_config.example.json, or run mt5-mcp directly and point Claude Code's MCP client at the stdio process. Once connected, ask Claude to read your account summary, list open positions, generate an EA draft, or summarize a Strategy Tester report — it calls the matching tool and shows you the audited result.

ChatGPT usage

ChatGPT connects over Streamable HTTP at /mcp. The main, recommended profile is chatgpt_full — full parity with Claude's full profile, same tools and same safety gates:

MT5_MCP_PROFILE=chatgpt_full
MT5_MCP_TRANSPORT=streamable-http
MT5_MCP_HTTP_TOKEN=<a long random string>
mt5-mcp

HTTP auth is required by default. If MT5_MCP_HTTP_TOKEN is unset the server refuses to start (a MT5_MCP_HTTP_ALLOW_NO_AUTH=true override exists for local-only development; never set it on anything reachable through a tunnel). The token controls who can reach the server; once authenticated, chatgpt_full grants the same capabilities Claude already has.

For a deliberately narrower connection, set MT5_MCP_PROFILE=chatgpt_safe — a read / inspect / analyze-only profile with no trading, no writes, and no way to submit broker credentials. It is optional, not the default. ChatGPT's custom connectors need an HTTPS URL, so put a tunnel (cloudflared / ngrok) in front of the local server — the full walkthrough, tunnel setup, and safety notes are in docs/CHATGPT_MCP.md.

Broker symbol resolution

Every symbol in this project's docs and examples — EURUSD, XAUUSD, GBPUSD, or any other ticker — is an example, not a limitation. Any symbol your connected broker supports can be requested (in any name or language); the agent resolves it dynamically against the real broker symbol list (mt5_symbols_list) before use. Full rule and alias table: docs/CLAUDE_CODE_AUTOMATION.md.

Documentation

Project structure

src/mt5_mcp/       server, profiles, tool registry, action router, all tool modules
tests/             one test file per module, mocked mt5_bridge
docs/              architecture, access model, consent flow, tool reference,
                   automation model, command playbook, backtest workflow,
                   ChatGPT connector setup
docs/assets/       README graphics (banner, overview, profiles, workflow,
                   safety, capabilities — original self-contained SVGs)
examples/          Claude config examples + a minimal MCP client
scripts/           readiness check, open-access self-check
backups/ consents/ drafts/ logs/ workspace/   runtime data (gitignored contents)

Testing

pytest          # 222 tests
ruff check .

The suite runs fully without MetaTrader5 or psutil installed and never calls a real order_send. See tests/conftest.py for the isolation fixtures that keep every test off the real filesystem.

Roadmap

• Streamable-HTTP transport alongside stdio. Done — see docs/CHATGPT_MCP.md.

• compare_backtests to diff two summarize_backtest outputs. Done.

• OAuth / per-user auth for the HTTP transport (today: a single shared bearer token).

• Strategy Tester automation via .ini launch configs (currently: report discovery/parsing only).

• Multi-account profile switching.

• Richer market depth / DOM support where brokers allow it.

License

Released under the MIT License — © 2026 Mt5_mcp contributors.