Usage

Quick Start

The server runs in stdio mode by default for MCP clients like Claude Desktop:

uv run mt5mcp

Development Mode (HTTP)

For testing with HTTP transport, create a .env file:

MT5_MCP_TRANSPORT=http
MT5_MCP_HOST=127.0.0.1
MT5_MCP_PORT=8000

Then run:

uv run mt5mcp

The server will start at http://127.0.0.1:8000

Installing for MCP Clients

Method 1: Using uvx (Simplest - No Installation Required) ⭐

Add this configuration to your MCP client's config file:

For Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "mcp-metatrader5-server": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/Qoyyuum/mcp-metatrader5-server",
        "mt5mcp"
      ]
    }
  }
}

Method 2: Using FastMCP Install (Recommended)

git clone https://github.com/Qoyyuum/mcp-metatrader5-server
cd mcp-metatrader5-server

After git cloning the repo, run the following commands:

For MCP JSON format

uv run fastmcp install mcp-json src/mcp_mt5/main.py

For Claude Desktop

uv run fastmcp install claude-desktop src/mcp_mt5/main.py

For Claude Code

uv run fastmcp install claude-code src/mcp_mt5/main.py

For Cursor

uv run fastmcp install cursor src/mcp_mt5/main.py

For Gemini CLI

uv run fastmcp install gemini-cli src/mcp_mt5/main.py

Method 3: Manual Configuration

Add this to your claude_desktop_config.json or whatever LLM config file:

{
  "mcpServers": {
    "mcp-metatrader5-server": {
      "command": "uvx",
      "args": [
        "--from",
        "mcp-metatrader5-server",
        "mt5mcp"
      ]
    }
  }
}

API Reference

Connection Management

• initialize(): Initialize the MT5 terminal
• login(account, password, server): Log in to a trading account
• shutdown(): Close the connection to the MT5 terminal

Market Data Functions

• get_symbols(): Get all available symbols
• get_symbols_by_group(group): Get symbols by group
• get_symbol_info(symbol): Get information about a specific symbol
• get_symbol_info_tick(symbol): Get the latest tick for a symbol
• copy_rates_from_pos(symbol, timeframe, start_pos, count): Get bars from a specific position
• copy_rates_from_date(symbol, timeframe, date_from, count): Get bars from a specific date
• copy_rates_range(symbol, timeframe, date_from, date_to): Get bars within a date range
• copy_ticks_from_pos(symbol, start_pos, count): Get ticks from a specific position
• copy_ticks_from_date(symbol, date_from, count): Get ticks from a specific date
• copy_ticks_range(symbol, date_from, date_to): Get ticks within a date range

Trading Functions

• order_send(request): Send an order to the trade server
• order_check(request): Check if an order can be placed with the specified parameters
• positions_get(symbol, group): Get open positions
• positions_get_by_ticket(ticket): Get an open position by its ticket
• orders_get(symbol, group): Get active orders
• orders_get_by_ticket(ticket): Get an active order by its ticket
• history_orders_get(symbol, group, ticket, position, from_date, to_date): Get orders from history
• history_deals_get(symbol, group, ticket, position, from_date, to_date): Get deals from history

Example Workflows

Connecting and Getting Market Data

# Initialize MT5
initialize()

# Log in to your trading account
login(account=123456, password="your_password", server="your_server")

# Get available symbols
symbols = get_symbols()

# Get recent price data for EURUSD
rates = copy_rates_from_pos(symbol="EURUSD", timeframe=15, start_pos=0, count=100)

# Shut down the connection
shutdown()

Placing a Trade

# Initialize and log in
initialize()
login(account=123456, password="your_password", server="your_server")

# Create an order request
request = OrderRequest(
    action=mt5.TRADE_ACTION_DEAL,
    symbol="EURUSD",
    volume=0.1,
    type=mt5.ORDER_TYPE_BUY,
    price=mt5.symbol_info_tick("EURUSD").ask,
    deviation=20,
    magic=123456,
    comment="Buy order",
    type_time=mt5.ORDER_TIME_GTC,
    type_filling=mt5.ORDER_FILLING_IOC
)

# Send the order
result = order_send(request)

# Shut down the connection
shutdown()

Resources

The server provides the following resources to help AI assistants understand how to use the MetaTrader 5 API:

• mt5://getting_started: Basic workflow for using the MetaTrader 5 API
• mt5://trading_guide: Guide for placing and managing trades
• mt5://market_data_guide: Guide for accessing and analyzing market data
• mt5://order_types: Information about order types
• mt5://order_filling_types: Information about order filling types
• mt5://order_time_types: Information about order time types
• mt5://trade_actions: Information about trade request actions

Prompts

The server provides the following prompts to help AI assistants interact with users:

• connect_to_mt5(account, password, server): Connect to MetaTrader 5 and log in
• analyze_market_data(symbol, timeframe): Analyze market data for a specific symbol
• place_trade(symbol, order_type, volume): Place a trade for a specific symbol
• manage_positions(): Manage open positions
• analyze_trading_history(days): Analyze trading history

Development

Project Structure

mcp-metatrader5-server/
├── src/
│   └── mcp_mt5/
│       ├── __init__.py      # Entry point with main()
│       ├── main.py          # FastMCP server with all tools
│       └── test_client.py   # Test client for development
├── docs/
│   ├── getting_started.md
│   ├── market_data_guide.md
│   ├── trading_guide.md
│   └── publishing.md
├── .env                     # Environment configuration (create from .env.example)
├── README.md
├── pyproject.toml           # Project metadata (using hatchling)
└── uv.lock                  # Dependency lock file

Building the Package

Using uv (recommended):

uv build

This will create wheel and source distributions in the dist/ directory.

Publishing to PyPI

Using uv:

# Build first
uv build

# Publish to PyPI
uv publish

# Or publish to TestPyPI first
uv publish --publish-url https://test.pypi.org/legacy/

License

MIT

Acknowledgements

• MetaQuotes for the MetaTrader 5 platform
• FastMCP for the MCP server implementation