yugen-mt5-mcp

🌐 Language: English | Español

📚 New to the project? Start with the documentation index — it explains the recommended reading order. TIP: toda la documentación también está disponible en español en docs/es/.

Secure, auditable MCP server for MetaTrader 5 — gives AI clients controlled access to market data, account state, and trade execution through a hardened gate with symbol allowlists, volume limits, and an append-only audit trail.

Quick Start (for users)

Prerequisites

• Windows with MetaTrader 5 installed and logged into a demo account
• uv installed

Run without installing

uvx yugen-mt5-mcp

Install persistently

uv tool install yugen-mt5-mcp
yugen-mt5-mcp

Validate your setup

yugen-mt5-mcp doctor

This runs all readiness checks (config, MT5 connection, audit path, transport) without starting the server.

Client Configuration

For the complete connection guide covering all 4 methods (STDIO, LAN remote, VPS/TLS), see docs/connection-methods.md.

Claude Desktop

Add the following to your Claude Desktop config file.

• Windows: C:\Users\YOUR_USERNAME\AppData\Roaming\Claude\claude_desktop_config.json
• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "yugen-mt5": {
      "command": "uvx",
      "args": ["yugen-mt5-mcp"],
      "env": {
        "YUGEN_MT5_ALLOWED_SYMBOLS": "EURUSD,XAUUSD",
        "YUGEN_MT5_ALLOW_LIVE_TRADING": "false",
        "YUGEN_MT5_ALLOW_REAL_ACCOUNTS": "false",
        "YUGEN_MT5_MAX_ORDER_VOLUME": "1.0",
        "YUGEN_MT5_MAX_SYMBOL_EXPOSURE": "1.0",
        "YUGEN_MT5_AUDIT_PATH": "C:\\Users\\YOUR_USERNAME\\AppData\\Local\\Yugen\\mt5-mcp\\audit.sqlite3"
      }
    }
  }
}

You can also generate this block automatically:

yugen-mt5-mcp config claude

Cursor

Add the following to ~/.cursor/mcp.json:

{
  "mcpServers": {
    "yugen-mt5": {
      "command": "uvx",
      "args": ["yugen-mt5-mcp"],
      "env": {
        "YUGEN_MT5_ALLOWED_SYMBOLS": "EURUSD,XAUUSD",
        "YUGEN_MT5_ALLOW_LIVE_TRADING": "false",
        "YUGEN_MT5_ALLOW_REAL_ACCOUNTS": "false",
        "YUGEN_MT5_MAX_ORDER_VOLUME": "1.0",
        "YUGEN_MT5_MAX_SYMBOL_EXPOSURE": "1.0"
      }
    }
  }
}

yugen-mt5-mcp config cursor

OpenCode

Add the following to ~/.config/opencode/config.json:

{
  "mcp": {
    "yugen-mt5": {
      "type": "local",
      "command": ["uvx", "yugen-mt5-mcp"],
      "environment": {
        "YUGEN_MT5_ALLOWED_SYMBOLS": "EURUSD,XAUUSD",
        "YUGEN_MT5_ALLOW_LIVE_TRADING": "false",
        "YUGEN_MT5_ALLOW_REAL_ACCOUNTS": "false",
        "YUGEN_MT5_MAX_ORDER_VOLUME": "1.0",
        "YUGEN_MT5_MAX_SYMBOL_EXPOSURE": "1.0"
      },
      "enabled": true
    }
  }
}

yugen-mt5-mcp config opencode

Configuration (Environment Variables)

All configuration is via YUGEN_MT5_* environment variables. You can generate an env block interactively:

yugen-mt5-mcp init

Trading safety model

Remote Transport (WSL / Mac to Windows MT5)

When your AI client runs in WSL, macOS, or a VPS and MetaTrader 5 is on a Windows host, use the HTTP remote transport:

# On the Windows host:
$env:YUGEN_MT5_REMOTE_ENABLED="true"
$env:YUGEN_MT5_REMOTE_BEARER_TOKEN="your-secret-token"
yugen-mt5-mcp run --transport remote

# Generate a client config block pointing at the Windows host:
yugen-mt5-mcp config remote --host 192.168.1.100 --port 8765 --token your-secret-token

Install the remote extra first:

uv tool install "yugen-mt5-mcp[remote]"

See docs/remote-transport.md for the full deployment guide, security model, and TLS setup. For the step-by-step VPS (EC2 + Caddy/TLS) walkthrough, see docs/connection-methods.md — Method 4.

For Contributors

Clone and install in editable mode

git clone https://github.com/YugenLabsTI/yugen-mt5-mcp.git
cd yugen-mt5-mcp
python -m pip install -e ".[dev]"

Run the test suite

pytest

MT5-dependent tests are automatically skipped on non-Windows platforms.

Run linting and type checks

ruff check src tests
mypy

Start the server locally

$env:YUGEN_MT5_ALLOWED_SYMBOLS="EURUSD,XAUUSD"
yugen-mt5-mcp run

For all CLI options see docs/cli.md. For installation variants see docs/install.md.

License

Apache-2.0 — see LICENSE.md. Copyright Yugen Labs S.A.S.