mcp-mt5

# MT5 Multi-Account MCP An [MCP](https://modelcontextprotocol.io) server that gives an AI assistant (Claude, etc.) direct **read** and optional **execution** access to **multiple MetaTrader 5 accounts at once** — positions, P&L, prices, indicators, history and logs, plus opening and closing trades — without screenshots. > ⚠️ **Disclaimer — read this.** This software can **place, modify and close REAL orders** > in MetaTrader 5. Use it entirely **at your own risk**. **Test on a DEMO account first.** > It is provided "AS IS", without warranty of any kind; the authors are **not liable for any > financial loss**. Execution is **OFF by default** — every account is read-only unless you > explicitly set `permitir_ejecucion: true`. ## Why this exists The official `MetaTrader5` Python package is a **singleton per process**: one `initialize()` connects to exactly one terminal, so you cannot read two accounts from a single process. This server solves that by launching **one worker subprocess per account**, each holding its own live connection. A parent process (FastMCP over stdio) routes every call to the right account's worker and reads CSV/log files directly. ``` MCP client ──stdio──▶ parent (FastMCP) ├── router ──▶ worker(Account A) ──▶ MT5 terminal A └── router ──▶ worker(Account B) ──▶ MT5 terminal B ``` ## Features **Read tools:** account info, open positions, pending orders, deal history, P&L by channel/symbol/day, live price/candles/spread, locally-computed indicators (RSI/MACD/ATR/Bollinger/EMA/SMA), the EA's CSV files and the Experts logs. **Execution tools (opt-in):** open market order, open pending order, modify SL/TP, close position (full or partial), cancel pending order. ## Requirements - Windows, with one or more **MetaTrader 5 terminals open and logged in** (the worker attaches to the running terminal; it never asks for your password). - Python 3.11+ (tested on 3.14). ## Install ```powershell python -m venv .venv .\.venv\Scripts\python.exe -m pip install -r requirements.txt ``` ## Configure Copy the template and edit it with your accounts: ```powershell copy mt5_mcp\cuentas.example.json mt5_mcp\cuentas.json ``` Each account entry: | Field | Meaning | |-------|---------| | `nombre` | Label you use in the tools (e.g. `"Broker1"`) | | `terminal_path` | Full path to that terminal's `terminal64.exe` | | `simbolo` | Default symbol for that account (brokers name it differently, e.g. `XAUUSD`, `XAUUSD.r`) | | `sufijo_csv` | Suffix of the EA's CSV files in `Common\Files` (optional) | | `terminal_hash` | The terminal's folder under `...\Terminal\<hash>` (for reading Experts logs) | | `permitir_ejecucion` | `true` enables execution tools for that account. **Default `false`** (read-only) | | `max_lotes` | Optional per-order volume cap. If omitted, no cap | Root keys: `magic_ejecucion` (the magic number this server stamps on its orders) and `common_files` / `terminals_root` paths. `cuentas.json` is gitignored so you never commit real accounts. ## Register in your MCP client `.mcp.json` (or your client's config): ```json { "mcpServers": { "mt5": { "command": "C:\\path\\to\\repo\\.venv\\Scripts\\python.exe", "args": ["-m", "mt5_mcp.server"], "cwd": "C:\\path\\to\\repo" } } } ``` Restart the client; tools appear as `mt5` / `mcp__mt5__*`. ## Tools Read-only: `cuentas`, `health`, `account_info`, `positions`, `orders`, `comparar`, `deals`, `pnl_por_canal`, `pnl_por_simbolo`, `stats_dia`, `precio`, `velas`, `spread`, `indicadores`, `leer_csv_ea`, `experts_log`. Execution (require `permitir_ejecucion: true`): `ejecutar_abrir_mercado`, `ejecutar_abrir_pendiente`, `ejecutar_modificar_sltp`, `ejecutar_cerrar`, `ejecutar_cancelar_pendiente`. > Tool names and code comments are in **Spanish** (the project's original language). > Functionality is language-independent. ## Security model - **Read-only by default**: an account without `permitir_ejecucion` cannot execute. - **Explicit, auditable execution**: execution tools are separate, prefixed `ejecutar_`, gated per account, with an optional `max_lotes` cap and their own magic number. - **Your MCP client asks for approval** before each execution tool call. - **No credentials**: it connects to the already-open terminal. - **No outbound network**: only the local terminal and files. ## Tests ```powershell .\.venv\Scripts\python.exe -m pytest mt5_mcp/tests -v ``` Unit tests (config, router, gating, analytics, indicators, file readers) run **without MetaTrader 5**. Live checks require the terminals open. ## License MIT — see [LICENSE](LICENSE).