agentleFS
ariadngariadng/metatrader-mcp-server/CLAUDE.md

metatrader-mcp-server

CLAUDE.md824 starsChanged 14 months agoMITView on GitHub

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/ariadng/metatrader-mcp-server Pattern: Functions receive connection as first param, use keyword-only args (*,)

The file

We split this CLAUDE.md into the rules it gives an agent

8 rules. About 0 are common, 4 are distinctive, and 4 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈4

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 4

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    Add to <module>/__init__.py and client_<module>.py

    line 134
  2. Distinctive:

    Use type hints and docstrings for all public functions

    line 163
  3. Very specific:

    Use keyword-only args (*,) for clarity

    line 165
  4. Distinctive:

    Test with demo accounts

    line 167
  5. Very specific:

    Update __init__.py when adding modules

    line 169
  6. Very specific:

    Use print() (use logging)

    line 176
  7. Distinctive:

    Test with live accounts without consent

    line 177
  8. Distinctive:

    Add emojis unless requested

    line 178

≈ “Common” is an estimate: at least 1 in 5 of the 26,980 CLAUDE.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
CLAUDE.md

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/ariadng/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)

Import Order

  1. Standard library (os, typing)
  2. Third-party (pandas, fastapi)
  3. Local (.exceptions, .types)

Common Patterns

Connection

from metatrader_client import MT5Client

# Minimal configuration
config = {"login": int(login), "password": password, "server": server}

# Full configuration with all available options
config = {
    "login": int(login),         # Required: MT5 account login
    "password": password,         # Required: MT5 account password
    "server": server,             # Required: MT5 server name
    "path": None,                 # Optional: Path to terminal executable (auto-detect if None)
    "timeout": 60000,             # Optional: Connection timeout in ms (default: 60000)
    "portable": False,            # Optional: Use portable mode (default: False)
    "max_retries": 3,             # Optional: Max connection retries (default: 3)
    "backoff_factor": 1.5,        # Optional: Retry delay multiplier (default: 1.5)
    "cooldown_time": 2.0,         # Optional: Seconds between connections (default: 2.0)
    "debug": False                # Optional: Enable debug logging (default: False)
}

client = MT5Client(config)
client.connect()
# operations...
client.disconnect()

Error Handling

# Client level
if type.upper() not in ["BUY", "SELL"]:
    return {"error": True, "message": "Invalid type", "data": None}

# API level
try:
    return client.operation()
except MT5ConnectionError as e:
    raise HTTPException(status_code=503, detail=str(e))

Testing Pattern

@pytest.fixture(scope="module")
def mt5_client():
    client = MT5Client({"login": int(os.getenv("LOGIN")), ...})
    client.connect()
    yield client
    client.disconnect()

Adding New Features

New Client Operation

  1. Create metatrader_client/<module>/new_operation.py
  2. Add to <module>/__init__.py and client_<module>.py
  3. Test in tests/metatrader_client/test_<module>.py

New MCP Tool

  1. Add to metatrader_mcp/server.py:
@mcp.tool()
def tool_name(ctx: Context, param: type) -> str:
    """Description for AI."""
    client = get_client(ctx)
    result = client.module.operation(param)
    return result.to_csv() if hasattr(result, 'to_csv') else result

New REST Endpoint

  1. Add to metatrader_openapi/routers/<module>.py:
@router.post("/path", response_model=Dict[str, Any])
async def endpoint(request: Request, param: type = Body(...)):
    """Description."""
    client = request.app.state.client
    return client.module.operation(param)

Critical Rules

✅ DO

  • Use type hints and docstrings for all public functions
  • Return consistent formats: {"error": bool, "message": str, "data": Any}
  • Use keyword-only args (*,) for clarity
  • Handle exceptions with custom exception classes
  • Test with demo accounts
  • Validate inputs (symbols, volumes, prices)
  • Update __init__.py when adding modules

❌ DON'T

  • Hardcode credentials (use env vars)
  • Mix business logic with routing
  • Skip error handling on trading operations
  • Modify connection object in functions
  • Use print() (use logging)
  • Test with live accounts without consent
  • Add emojis unless requested

MetaTrader 5 Specifics

Order Types: BUY, SELL, BUY_LIMIT, SELL_LIMIT, BUY_STOP, SELL_STOP, BUY_STOP_LIMIT, SELL_STOP_LIMIT Timeframes: M1, M5, M15, M30, H1, H4, D1, W1, MN1 Filling Modes: Broker-dependent (FOK, IOC, Return) Platform: Windows-centric (MT5 terminal required) Symbol Format: Broker-dependent (e.g., "EURUSD", "EURUSD.m")


Environment Variables

Required: LOGIN, PASSWORD, SERVER Optional: MT5_PATH (path to MT5 terminal executable, auto-detected if not set), OPENAPI_TITLE, OPENAPI_VERSION MCP Transport: MCP_TRANSPORT (sse|stdio|streamable-http, default: sse), MCP_HOST (default: 0.0.0.0), MCP_PORT (default: 8080) Debug: Set debug: True in config dict


Testing & Debugging

# Run tests
pytest tests/                           # All
pytest tests/metatrader_client/         # Client only
pytest tests/test_orders_route.py       # Specific

# Debug
client.is_connected()                   # Check connection
client.get_terminal_info()              # Terminal details
client.last_error()                     # Get last error

Project Goals

  1. Accessibility - Natural language trading for non-programmers
  2. Modularity - Independent, reusable components
  3. Safety - Prevent accidental losses through validation
  4. Reliability - Robust error handling and connection management
  5. Extensibility - Easy to add operations and integrations

Resources


Note: This is financial software. Changes can result in real money loss. Test thoroughly with demo accounts.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.