jsfrnc/mt5-docker-api repository overview

⁠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

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

1. Configure environment:

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

1. Start the container:

docker compose up -d

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

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

⁠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

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

⁠Support this project

Free, and maintained on my own time. Sponsorship covers the market data and broker API access behind these tools, and keeps them working when brokers change their export formats.