MetaTrader5 Docker API

A containerized solution for running MetaTrader5 trading platform with web-based VNC access and Python API support.

🐳 Docker Hub

The official image is available on Docker Hub:

Repository: jsfrnc/mt5-docker-api

docker pull jsfrnc/mt5-docker-api:latest

Overview

This Docker image allows you to run MetaTrader5 on any system that supports Docker, providing:

• Web-based access through VNC (no VNC client needed)
• Python API for algorithmic trading
• Persistent storage for configurations and data
• Automated installation and setup

Features

• Cross-Platform: Run Windows-only MT5 on Linux/Mac systems
• Web Access: Access MT5 through any web browser on port 3000
• Python Integration: Built-in support for automated trading via Python
• Auto-Installation: MT5 installs automatically on first run
• Persistent Data: All settings and data persist across container restarts
• Health Monitoring: Built-in health checks for reliability
• Optimized Performance: Multi-stage build for smaller image size

Quick Start

Option 1: Using Docker Hub Image (Easiest)

Pull and run the latest image from Docker Hub:

# Pull the latest image
docker pull jsfrnc/mt5-docker-api:latest

# Run the container
docker run -d \
  --name mt5-docker \
  -p 3000:3000 \
  -p 8000:8000 \
  -p 8001:8001 \
  -e VNC_PASSWORD=yourpassword \
  -v mt5_data:/root/.wine/drive_c/Program\ Files/MetaTrader\ 5 \
  jsfrnc/mt5-docker-api:latest

Available tags:

• jsfrnc/mt5-docker-api:latest - Latest stable version
• jsfrnc/mt5-docker-api:v1.0.2 - Specific version

Option 2: Using Docker Compose (Recommended for Production)

1. Create a project directory:

mkdir mt5-docker && cd mt5-docker

2. Download required files:

wget https://raw.githubusercontent.com/jefrnc/mt5-docker-api/main/docker-compose.yml
wget https://raw.githubusercontent.com/jefrnc/mt5-docker-api/main/.env.example

3. Configure environment:

cp .env.example .env
nano .env  # Edit with your settings

4. Start the container:

docker compose up -d

The image jsfrnc/mt5-docker-api:latest will be automatically pulled from Docker Hub.

5. Access MetaTrader5:
   • Open your browser and navigate to http://localhost:3000
   • Enter the VNC password you set in .env
   • API documentation available at http://localhost:8000/docs

Using Docker CLI

docker run -d \
  -p 3000:3000 \
  -p 8000:8000 \
  -p 8001:8001 \
  -v mt5_data:/root/.wine/drive_c/Program\ Files/MetaTrader\ 5 \
  -e VNC_PASSWORD=yourpassword \
  -e MT5_LOGIN=your_login \
  -e MT5_PASSWORD=your_password \
  -e MT5_SERVER=your_server \
  jsfrnc/mt5-docker-api:latest

Configuration

Environment Variables

Variable	Required	Default	Description
VNC_PASSWORD	Yes	-	VNC connection password
MT5_LOGIN	No	-	MetaTrader5 account login
MT5_PASSWORD	No	-	MetaTrader5 account password
MT5_SERVER	No	-	MetaTrader5 broker server
API_KEY	No	-	API key for authenticating REST API requests via X-API-Key header. If not set, auth is disabled (for local dev)
ALLOWED_ORIGINS	No	http://localhost:8080	Comma-separated list of allowed CORS origins
VNC_PORT	No	3000	Web VNC interface port
API_PORT	No	8000	REST API server port
MT5_PORT	No	8001	Python MT5 server port
WINEPREFIX	No	/root/.wine	Wine prefix directory
MT5_VERSION	No	5.0.36	MetaTrader5 Python library version
WINE_VERSION	No	win10	Wine compatibility mode
LOG_LEVEL	No	INFO	Logging verbosity

Volume Mounts

• /root/.wine/drive_c/Program Files/MetaTrader 5: MT5 installation and data (persistent across restarts)
• /app/logs: Application logs

API Usage

REST API

The container includes a REST API with automatic documentation:

• API Documentation: http://localhost:8000/docs
• OpenAPI Schema: http://localhost:8000/openapi.json

Example API Calls:

# Get account info (include X-API-Key header if API_KEY is configured)
curl -H "X-API-Key: YOUR_KEY" http://localhost:8000/account

# Get available symbols
curl http://localhost:8000/symbols

# Get symbol details
curl http://localhost:8000/symbol/EURUSD

# Place an order
curl -X POST http://localhost:8000/order \
  -H "Content-Type: application/json" \
  -d '{
    "symbol": "EURUSD",
    "volume": 0.01,
    "order_type": "BUY"
  }'

# Get open positions
curl http://localhost:8000/positions

# Get historical data
curl -X POST http://localhost:8000/history/candles \
  -H "Content-Type: application/json" \
  -d '{
    "symbol": "EURUSD",
    "timeframe": "M5",
    "start": "2024-01-01T00:00:00",
    "end": "2024-01-02T00:00:00"
  }'

WebSocket for Real-time Data

// Connect to real-time tick stream
const ws = new WebSocket('ws://localhost:8000/ws/ticks/EURUSD');

ws.onmessage = (event) => {
  const tick = JSON.parse(event.data);
  console.log(`${tick.symbol}: Bid=${tick.bid}, Ask=${tick.ask}`);
};

Python Direct Connection

You can also connect directly to MT5 without the REST API:

from mt5linux import MetaTrader5

# Connect to the container
mt5 = MetaTrader5(host='localhost', port=8001)
mt5.initialize()

# Check version
print(mt5.version())

# Your trading logic here

MQL5 Scripts Location

If you mount the MT5 volume locally, place your Expert Advisors and Scripts in:

./mt5/MQL5/

Access MetaEditor through the MT5 interface for development.

Building from Source

1. Clone the repository:

git clone https://github.com/jefrnc/mt5-docker-api
cd mt5-docker-api

2. Build the image:

docker build -t mt5-docker-api:latest .

System Requirements

• Docker Engine 20.10+
• 4GB RAM minimum
• 10GB disk space
• x86_64/amd64 architecture (ARM not supported)

Security Considerations

• Always use strong passwords
• Run with minimal privileges
• Keep the image updated
• Use environment variables for sensitive data
• Consider network isolation for production use

Troubleshooting

Container won't start

• Check logs: docker logs mt5
• Verify ports 3000 and 8001 are not in use
• Ensure sufficient disk space

Can't connect to VNC

• Verify container is running: docker ps
• Check firewall settings
• Try accessing http://localhost:3000 directly

MT5 installation fails

• Check internet connectivity
• Verify Wine is working: docker exec mt5 wine --version
• Review installation logs

Python API connection issues

• Ensure port 8001 is exposed
• Check mt5linux server is running
• Verify network connectivity

Performance Tips

• Allocate at least 2 CPU cores
• Use SSD storage for better I/O
• Limit concurrent connections
• Monitor resource usage

License

This project is licensed under the MIT License. See LICENSE for details.