English | 中文

This project is based on ariadng/metatrader-mcp-server with the following enhancements:

1. Automatic pre-trade validation — all orders are validated internally before submission (margin check, order_check)
2. Portable mode support — run MT5 terminal in portable mode via --portable flag or MT5_PORTABLE env var
3. Real-time WebSocket quote streaming — stream live tick data to connected clients (inherited from base)

What's New vs ariadng/metatrader-mcp-server

1. Automatic Pre-Trade Validation

All order placement functions now perform automatic pre-trade checks internally.

When you call place_market_order or place_pending_order, the system automatically:

1. Validates symbol availability — ensures the trading symbol exists and is accessible
2. Calculates required margin — uses MT5's order_calc_margin() to determine margin requirements
3. Checks free margin sufficiency — verifies your account has enough free margin
4. Validates order parameters — calls MT5's order_check() to validate all order parameters

If any validation fails, the order is rejected before being sent to the broker. This prevents:

• Insufficient margin errors
• Invalid order parameters
• Broker rejections due to validation issues

2. Portable Mode Support

MT5 terminals installed in portable mode (e.g. on a USB drive or non-standard path) can now be used:

# CLI flag
metatrader5-mcp-server --login 12345 --password secret --server Broker-Demo --portable

# Environment variable
MT5_PORTABLE=true metatrader5-mcp-server --login 12345 --password secret --server Broker-Demo

Portable mode defaults to True for maximum compatibility.

Installation

pip install metatrader5-mcp-server

Or install from source:

git clone https://github.com/wwplay1978/metatrader5-mcp-server
cd metatrader5-mcp-server
pip install -e .

Requirements: Windows, Python 3.10+, MetaTrader 5 terminal installed.

Quick Start

MCP Server (stdio — for Claude Desktop / Claude Code)

Add to ~/.claude/mcp.json:

{
  "mcpServers": {
    "metatrader5": {
      "command": "python",
      "args": [
        "-m", "metatrader_mcp",
        "--login", "YOUR_LOGIN",
        "--password", "YOUR_PASSWORD",
        "--server", "YOUR_BROKER_SERVER",
        "--portable"
      ],
      "type": "stdio"
    }
  }
}

HTTP / REST API Server

metatrader-http-server --login 12345 --password secret --server Broker-Demo
# OpenAPI docs at http://localhost:8000/docs

WebSocket Quote Server

metatrader-quote-server --login 12345 --password secret --server Broker-Demo
# Streams live tick data over WebSocket

MCP Tools Reference

Account

| Tool | Description | |------|-------------| | get_account_info | Account balance, equity, margin |

Market

| Tool | Description | |------|-------------| | get_symbols | List available symbols | | get_symbol_info | Symbol specification | | get_candles | OHLCV candlestick data | | get_tick | Latest tick price |

Orders & Positions

| Tool | Description | |------|-------------| | place_market_order | Execute a market order (with automatic pre-trade validation) | | place_pending_order | Place a limit/stop order (with automatic pre-trade validation) | | close_position | Close an open position | | get_open_positions | List open positions | | get_pending_orders | List pending orders |

History

| Tool | Description | |------|-------------| | get_history_orders | Historical orders | | get_history_deals | Historical deals |

Environment Variables

| Variable | Default | Description | |----------|---------|-------------| | LOGIN | — | MT5 account login | | PASSWORD | — | MT5 account password | | SERVER | — | MT5 broker server name | | MT5_PATH | auto | Path to MT5 terminal executable | | MT5_PORTABLE | true | Enable portable mode | | MCP_TRANSPORT | sse | Transport: sse, stdio, streamable-http | | MCP_HOST | 0.0.0.0 | MCP server host | | MCP_PORT | 8080 | MCP server port |

Architecture

metatrader5-mcp-server/
├── src/
│   ├── metatrader_client/     # Core MT5 library (connection, orders, market, history)
│   ├── metatrader_mcp/        # MCP server (FastMCP, stdio/SSE transport)
│   ├── metatrader_openapi/    # REST API (FastAPI, OpenAPI docs)
│   └── metatrader_quote/      # WebSocket quote streaming server
└── tests/

Credits

• Base project: ariadng/metatrader-mcp-server
• Pre-trade check pattern inspired by amirkhonov/metatrader5-mcp
• MetaTrader 5 Python API: mql5.com/en/docs/python_metatrader5

License

MIT — see LICENSE

Note: This is financial software. Always test with a demo account before using with real funds.