Getting Started

Relevant source files

The following files were used as context for generating this wiki page:

• README.md
• pyproject.toml
• DOCKER_COMPOSE_USAGE.md
• mt5linux/settings.py
• mt5linux/constants.py
• mt5linux/main.py
• mt5linux/models.py

The mt5linux project provides a gRPC-based bridge that enables Linux systems to interact with MetaTrader 5 (MT5). Since MT5 is natively a Windows application, this library uses a client-server architecture where a gRPC bridge server runs in a Windows or Wine environment (often containerized via Docker) and a Python client interacts with it from Linux.

Sources: README.md:3-10, pyproject.toml:6-12

System Architecture

The architecture consists of three primary layers: the MT5 Terminal (running on Windows/Wine), the gRPC Bridge Server, and the Python Client (Sync or Async).

Installation

The package requires Python 3.13+ and can be installed via pip.

pip install mt5linux

Sources: README.md:20-22, pyproject.toml:29-30

Requirements

Component	Requirement
Python	3.13+
gRPC	grpcio 1.60.0+
Data	numpy 2.1+
Validation	pydantic 2.10.0+

Sources: pyproject.toml:19-27, README.md:13-18

Server Configuration

To use the library, you must have a running gRPC bridge server. There are two primary deployment methods.

Option 1: Docker (Recommended)

Docker is used for a containerized MT5 setup. Configuration is managed via environment variables and docker-compose.yaml.

# Start with default ports (e.g., 28812)
docker compose up -d

# Custom production ports
MT5_GRPC_PORT=38812 MT5_VNC_PORT=33000 docker compose up -d

Sources: README.md:112-118, DOCKER_COMPOSE_USAGE.md:5-15

Option 2: Standalone Bridge

If running directly on Windows where MT5 is installed, you can start the server using the module's entry point.

python -m mt5linux --server --host 0.0.0.0 --port 50051

Sources: mt5linux/main.py:10-15, README.md:122-132

Client Usage

The library provides both synchronous and asynchronous clients. Both clients implement the standard MT5 Python API.

Synchronous Client

The MetaTrader5 class provides a blocking interface suitable for traditional scripts.

from mt5linux import MetaTrader5

with MetaTrader5(host="localhost", port=28812) as mt5:
    mt5.initialize(login=12345, password="password", server="Broker-Demo")
    account = mt5.account_info()
    print(f"Balance: {account.balance}")

Sources: README.md:34-45, mt5linux/main.py:47-50

Asynchronous Client

The AsyncMetaTrader5 class is designed for asyncio applications, allowing parallel data fetching.

from mt5linux import AsyncMetaTrader5
import asyncio

async def run():
    async with AsyncMetaTrader5(host="localhost", port=28812) as mt5:
        await mt5.initialize(login=12345)
        account, tick = await asyncio.gather(
            mt5.account_info(),
            mt5.symbol_info_tick("EURUSD")
        )

Sources: README.md:53-65, mt5linux/main.py:54-58

Configuration and Environment Variables

Configuration is centralized in mt5linux/settings.py using Pydantic Settings. All variables can be overridden using the MT5_ prefix.

Variable	Default	Description
MT5_HOST	localhost	Server address
MT5_GRPC_PORT	8001	Internal gRPC port
MT5_DOCKER_GRPC_PORT	38812	Production host-mapped port
MT5_TEST_GRPC_PORT	28812	Isolated port for testing
MT5_LOGIN	0	Default account login

Sources: mt5linux/settings.py:44-75, DOCKER_COMPOSE_USAGE.md:18-35

Pydantic Models

The library uses type-safe Pydantic models to represent MT5 data structures, such as AccountInfo, SymbolInfo, and OrderRequest.

Summary

To get started with mt5linux, install the package and deploy the gRPC bridge server via Docker. Once the server is running, use the MetaTrader5 or AsyncMetaTrader5 clients to interact with your MT5 terminal. All configurations, from networking to trading defaults, are managed via environment variables for maximum flexibility in Docker and CI/CD environments.

Sources: README.md:143-160, DOCKER_COMPOSE_USAGE.md:88-100