MetaTrader 5 (MT5) MCP Server & Web GUI Workstation

Python 3.10+ MCP MetaTrader 5 License: MIT

A high-performance Model Context Protocol (MCP) Server and interactive Web GUI Workstation for MetaTrader 5 on Windows. This project connects AI assistants (Antigravity, Claude Desktop, Cursor, etc.) and quantitative traders directly to their local MT5 installation to:

Pull historical market data (OHLCV bars across timeframes M1–MN1 and millisecond-precision tick streams) with high-speed Parquet and CSV exports.
Execute strategy backtests via built-in Python quantitative engines and native MT5 Strategy Tester automation (terminal64.exe /config:tester.ini).
Inspect demo account status, equity curves, active symbols, market watch quotes, and open positions.
Interactive Financial Web GUI: Built with TradingView Lightweight Charts, real-time telemetry, Strategy Studio with equity curve visualizer, and account login manager.
Strict Trading Safety Guard: Ensures demo and live orders can only execute with explicit confirmation.

Architecture Overview

 ┌────────────────────────────────────────────────────────┐
 │                      AI Client                         │
 │        (Antigravity / Claude Desktop / Cursor)         │
 └───────────────────────────┬────────────────────────────┘
                             │ MCP Protocol (stdio)
 ┌───────────────────────────▼────────────────────────────┐
 │                  MT5 MCP Server (Python)               │
 │   - FastMCP Server (`src/mt5_mcp/server.py`)           │
 │   - Data Caching & Parquet/CSV Export Engine           │
 │   - Quantitative Strategy Backtesting Engine           │
 └─────────────┬────────────────────────────┬─────────────┘
               │                            │
 ┌─────────────▼──────────────┐  ┌──────────▼─────────────┐
 │    MetaTrader5 Python API  │  │ MT5 Native Tester Auto │
 │  - copy_rates_range()      │  │  - tester.ini builder  │
 │  - copy_ticks_range()      │  │  - terminal64.exe CLI  │
 │  - account_info() / login()│  │  - Report XML/HTML     │
 └─────────────┬──────────────┘  └──────────┬─────────────┘
               │                            │
 ┌─────────────▼────────────────────────────▼─────────────┐
 │               MetaTrader 5 Windows Terminal            │
 │               (Demo Account Connected)                 │
 └────────────────────────────────────────────────────────┘

Installation & Prerequisites

1. Requirements

Windows 10 / 11 (64-bit)
MetaTrader 5 desktop terminal installed
Python 3.10, 3.11, or 3.12 (64-bit)
uv (recommended) or standard pip

2. Enable Algorithmic Trading in MT5

In your MetaTrader 5 terminal:

Navigate to Tools -> Options -> Expert Advisors.
Check Allow algorithmic trading.
Check Allow DLL imports (if required by custom indicators).

3. Setup Virtual Environment

# Clone the repository
git clone https://github.com/remomein05/mt5-mcp.git
cd mt5-mcp

# Create virtual environment and install dependencies
uv venv --python 3.12 .venv
.venv\Scripts\activate
uv pip install -e ".[dev]"

Web GUI Workstation (Interactive Dashboard)

The repository includes a dedicated financial-grade Web GUI Dashboard with TradingView charting, real-time market watch, strategy backtesting studio, and account management:

# Launch via console script
mt5-mcp-gui

# Or launch via Python module
.venv\Scripts\python -m mt5_mcp.gui --port 8000

Then open http://127.0.0.1:8000 in your browser.

GUI Features:

📊 TradingView Lightweight Charts: Smooth candlestick and volume charting with interactive timeframe selector (M1, M5, M15, M30, H1, H4, D1).
📈 Strategy Backtest Studio: Configure strategy parameters (SMA Crossover, RSI Reversal, Bollinger Bands), run simulations, and inspect Equity Growth Curves, KPIs (Sharpe ratio, Max Drawdown %, Win Rate %), and closed trades logs.
📦 Historical Data Exporter: Instant one-click extraction of candlestick data to Parquet and CSV files.
🔍 Market Watch: Real-time symbol exploration with wildcard search (e.g. *USD*, Crypto*) and live floating spread indicators.
⚙️ MT5 Connect & Account Login Modal: Seamlessly connect to your active MT5 terminal or switch/log in to any demo account with custom Login ID, Password, Broker/Server, and optional executable path (with Enter key submission and Esc key dismissal).
📋 Open Positions & Native MT5 Tester Panel: View open trades and automate native MQL5 Expert Advisors headlessly with batch .ini configurations.

MCP Client Configuration

Claude Desktop / Antigravity / Cursor (`mcp_config.json`)

Add the MT5 MCP server to your MCP client configuration:

{
  "mcpServers": {
    "mt5": {
      "command": "C:\\Users\\<USER>\\source\\repos\\mt5_mcp\\.venv\\Scripts\\python.exe",
      "args": [
        "-m",
        "mt5_mcp.server"
      ],
      "env": {
        "PYTHONUNBUFFERED": "1"
      }
    }
  }
}

Available MCP Tools

1. Connection & Account Management

Tool	Parameters	Description
`mt5_connect`	`path`, `login`, `password`, `server`	Initializes connection to MT5 terminal or logs in to a specific demo account.
`mt5_account_summary`	None	Returns demo account balance, equity, leverage, free margin, and profit.
`mt5_terminal_info`	None	Returns MT5 build version, connection state, ping, and data directories.

2. Market Exploration & Historical Data

Tool	Parameters	Description
`mt5_get_symbols`	`group` (e.g. `USD`)	Searches available symbols with wildcard filtering.
`mt5_symbol_details`	`symbol` (e.g. `EURUSD`)	Returns contract specifications (spread, point, digits, swap rates).
`mt5_symbol_current_tick`	`symbol`	Retrieves real-time bid, ask, and last price.
`mt5_fetch_historical_bars`	`symbol`, `timeframe`, `count`, `date_from`, `date_to`, `export_format`	Extracts historical OHLCV data across timeframes (`M1` to `MN1`) with optional Parquet/CSV export.
`mt5_fetch_ticks`	`symbol`, `count`, `date_from`, `date_to`, `export_format`	Extracts millisecond-precision tick streams with optional Parquet/CSV export.

3. Strategy Testing & Simulation

Tool	Parameters	Description
`mt5_list_backtest_strategies`	None	Lists built-in backtest models (`sma_crossover`, `rsi_reversal`, `bollinger_bands`).
`mt5_run_strategy_backtest`	`symbol`, `timeframe`, `strategy_name`, `bars_count`, `initial_cash`, `lot_size`, `params`	Executes backtest on historical MT5 data and returns Sharpe ratio, Max Drawdown %, Win Rate %, Profit Factor, and trade log.
`mt5_run_native_tester`	`expert_name`, `symbol`, `period`, `deposit`, `currency`, `leverage`, `model`, `from_date`, `to_date`, `visual`	Automates native MT5 Strategy Tester using generated `.ini` configs and headless `terminal64.exe` execution.

4. Positions & Trading (Guarded)

Tool	Parameters	Description
`mt5_get_open_positions`	`symbol` (optional)	Lists open positions on the demo account.
`mt5_get_order_history`	`days`, `symbol` (optional)	Lists closed deals and historical order executions.
`mt5_place_demo_order`	`symbol`, `order_type`, `volume`, `sl`, `tp`, `explicit_user_approval`	Places demo orders with strict safety guard requiring `explicit_user_approval=True`.

Running Tests

Run the comprehensive pytest suite verifying connectivity, historical extraction, quantitative backtesters, and GUI REST APIs:

.venv\Scripts\pytest -v

License

MIT License.