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 mt5data:/root/.wine/drivec/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)

• Create a project directory:

mkdir mt5-docker && cd mt5-docker

• 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

• Configure environment:

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

• Start the container:

docker compose up -d

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

• Access MetaTrader5:

Using Docker CLI

docker run -d \
  -p 3000:3000 \
  -p 8000:8000 \
  -p 8001:8001 \
  -v mt5data:/root/.wine/drivec/Program\ Files/MetaTrader\ 5 \
  -e VNC_PASSWORD=yourpassword \
  -e MT5LOGIN=yourlogin \
  -e MT5PASSWORD=yourpassword \
  -e MT5SERVER=yourserver \
  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

• Clone the repository:

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

• 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.