MetaTrader 5 MCP Server

MetaTrader 5 MCP Server

A Model Context Protocol (MCP) server that provides comprehensive access to MetaTrader 5 trading platform functionality through Python.

📖 New to this project? Check out the Quick Start Guide for a condensed reference!

🚀 Quick Start

Prerequisites

• MetaTrader 5 terminal installed and running on Windows
• Python 3.10+

Installation (Choose One Method)

Method 1: Automated Installation (Recommended)

Windows:

# Clone the repository
git clone https://github.com/amirkhonov/metatrader5-mcp.git
cd metatrader5-mcp

# Run installation script
install.bat

Linux/Mac:

# Clone the repository
git clone https://github.com/amirkhonov/metatrader5-mcp.git
cd metatrader5-mcp

# Run installation script
chmod +x install.sh
./install.sh

Method 2: Using pip

# Install from source
git clone https://github.com/amirkhonov/metatrader5-mcp.git
cd metatrader5-mcp
pip install -r requirements.txt
pip install -e .

Method 3: Using Poetry

git clone https://github.com/amirkhonov/metatrader5-mcp.git
cd metatrader5-mcp
poetry install

Configuration

1. Copy the environment template:

   cp .env.example .env
   

2. Edit .env with your MT5 credentials:

   MT5_LOGIN=12345678
   MT5_PASSWORD=your_password
   MT5_SERVER=MetaQuotes-Demo
   MT5_PATH=C:\Program Files\MetaTrader 5\terminal64.exe
   

3. Run the server:

   # Using environment variables from .env
   metatrader5-mcp
   
   # Or with command line arguments
   metatrader5-mcp --login 12345 --password secret --server MetaQuotes-Demo
   

Quick Test

# Check if the server starts correctly
metatrader5-mcp --help

Features

This MCP server exposes 32 tools for interacting with MT5, organized into the following categories:

🔌 Connection & Initialization

• Initialize/shutdown MT5 connection
• Get terminal version and information
• Login to trading accounts
• Get last error information

💰 Account Information

• Retrieve account balance, equity, margin, profit
• Get account settings and leverage

📊 Market Data

• Access symbol information and current prices
• Retrieve historical bar data (OHLCV) by date or position
• Get tick data with various filters and date ranges
• Manage Market Watch symbols

📈 Trading Operations

• Send market and pending orders
• Check order validity before execution
• Calculate required margin
• Calculate potential profit/loss

📋 Position & Order Management

• View open positions
• Monitor pending orders
• Access trading history (orders and deals)
• Filter by symbol, date range, or ticket

Prerequisites

• MetaTrader 5 terminal installed and running on Windows
• Python 3.10+

Installation Methods

Choose the method that works best for you:

Option 1: Quick Install Script (Easiest)

Windows:

install.bat

Linux/Mac:

./install.sh

The script will:

• Check Python version
• Create a virtual environment
• Install all dependencies
• Create a .env configuration file
• Guide you through setup

Option 2: Manual Installation with pip

# Install dependencies
pip install -r requirements.txt

# Install the package
pip install -e .

# Copy environment template
cp .env.example .env
# Edit .env with your credentials

Option 3: Using Poetry

poetry install
cp .env.example .env
# Edit .env with your credentials

Option 4: Using pipx (Global Install)

pipx install .

Option 5: Docker (Experimental)

# Build and run
docker-compose up -d

# View logs
docker-compose logs -f

Note: Docker support is experimental as MT5 requires Windows. Best for development/testing.

Configuration

For Claude Desktop

Add this configuration to your Claude Desktop config file:

Windows: %APPDATA%\Claude\claude_desktop_config.json

With Auto-Initialization (Recommended)

{
  "mcpServers": {
    "metatrader": {
      "command": "metatrader5-mcp",
      "args": [
        "--login",    "YOUR_MT5_LOGIN",
        "--password", "YOUR_MT5_PASSWORD",
        "--server",   "YOUR_MT5_SERVER",
        "--path",     "C:\\Program Files\\MetaTrader 5\\terminal64.exe"
      ]
    }
  }
}

Command Line Arguments

The server supports the following optional arguments:

• --login LOGIN - Trading account number
• --password PASSWORD - Trading account password
• --server SERVER - Trading server name (e.g., "MetaQuotes-Demo")
• --path PATH - Path to MT5 terminal executable

Running Locally

# With auto-initialization
metatrader5-mcp --login 12345 --password secret --server MetaQuotes-Demo

# Without initialization (ma