metatrader-mcp-server: Instructions file for Claude Code

Claude Development Guide - MetaTrader MCP Server

Project Overview

MCP server enabling AI assistants to trade on MetaTrader 5 via natural language. Provides both MCP (stdio) and HTTP/REST interfaces.

Stack: Python 3.10+ • FastMCP • FastAPI • MetaTrader5 SDK • Pandas • Pydantic • pytest Version: 0.5.1 (Beta) Repo: https://github.com/joangrcia/metatrader-mcp-server

---

Architecture (3 Packages)

1. metatrader_client - Core MT5 Library

metatrader_client/
├── account/      # Balance, equity, margin operations
├── connection/   # MT5 connection management with retry/cooldown
├── history/      # Historical deals and orders
├── market/       # Prices, candles, symbols
├── order/        # Trade execution and position management
├── types/        # Enums (OrderType, Timeframe, TradeAction, etc.)
└── client.py     # Main MT5Client class

Pattern: Functions receive connection as first param, use keyword-only args (*,)

def place_market_order(connection, *, type: str, symbol: str, volume: Union[float, int]):

2. metatrader_mcp - MCP Server

• FastMCP with SSE transport (default), STDIO fallback via --transport stdio
• Tools: @mcp.tool() decorated functions
• Client access: client = get_client(ctx)
• Returns: CSV strings for DataFrames, dicts for objects

3. metatrader_openapi - REST API

• FastAPI with OpenAPI docs at /docs
• Routers: accounts, market, orders, positions, history
• Client: request.app.state.client
• CORS enabled, lifespan-managed connection

---

Key Conventions

Code Style

# Function pattern
def operation(connection, *, param: type, optional: Optional[type] = None):
    """Brief description.

    Args:
        connection: MT5 connection object
        param: Description
        optional: Description (default: None)

    Returns:
        dict: {"error": bool, "message": str, "data": Any}
    """

Return Formats

• Client operations: {"error": False, "message": "...", "data": {...}} (dict) or DataFrame
• MCP tools: df.to_csv() for DataFrames, dict/list for objects
• REST endpoints: df.to_dict(orient="records") or dict (auto JSON)