# metaeditor5-mcp

MCP server that lets an AI author MQL5 Expert Advisors/indicators/scripts, compile them with
MetaEditor's CLI, and backtest them with MetaTrader 5's Strategy Tester — without a human
driving the MetaEditor/MetaTrader GUI.

## What this does and doesn't do

- **Does**: write/read/list/delete `.mq5`/`.mqh`/`.mqproj`/`.set` files under the MetaTrader
  data folder's `MQL5` tree, compile them via `MetaEditor64.exe /compile`, and run them
  through the Strategy Tester via `terminal64.exe /config` for historical backtesting.
- **Doesn't**: attach an EA to a live/demo chart or place any real order. Backtesting is a
  closed historical simulation with no live connection. Deploying an EA to actually trade is
  a manual step in the MetaTrader terminal GUI, and this project intentionally does not
  automate it.
- **Doesn't**: accept arbitrary/absolute filesystem paths. Every path-taking tool only accepts
  paths relative to the MQL5 sandbox root (`Experts`, `Include`, `Indicators`, `Scripts`,
  `Libraries`, `Files`), validated to reject `..` traversal and anything resolving outside it.

## Requirements

- **Windows.** MetaEditor/MetaTrader 5 desktop only ships for Windows, and this server shells
  out to `MetaEditor64.exe`/`terminal64.exe` directly, so it only runs on Windows (including
  inside a Windows VM) — not macOS/Linux, even if MT5 is run there under Wine.
- **MetaTrader 5** installed (which includes MetaEditor). Any broker's installer works — the
  server doesn't hardcode any broker.
- **Node.js 18+**.

## Setup

```bash
git clone https://github.com/dchumari/metaeditor5-mcp.git
cd metaeditor5-mcp
npm install
npm run build
```

Add to Claude Code's MCP config (`.mcp.json`), replacing the path below with the absolute
path to wherever you cloned this repo:

```json
{
  "mcpServers": {
    "metaeditor5": {
      "command": "node",
      "args": ["C:\\path\\to\\metaeditor5-mcp\\dist\\index.js"]
    }
  }
}
```

The server auto-detects your MetaTrader 5 installation and its data folder by scanning
`%APPDATA%\MetaQuotes\Terminal\*\origin.txt`. If you have more than one installation, set
`MCP_MT5_INSTALL_DIR` to the one you want (e.g. `C:\Program Files\MetaTrader 5`), or pass
`installDirHint` to the `get_environment_info` tool.

### Backtesting requires an account login

Verified empirically: MetaTrader's Strategy Tester refuses to start with no account
specified ("tester not started because the account is not specified"), even for a pure
historical simulation. To use `run_backtest`, log into any demo or live account in the
MetaTrader 5 terminal (File → Login to Trade Account, or open a new demo account) with
**"Save my login details"** checked.

That's normally the only setup step needed: `run_backtest` resolves the login to use, in
order, from (1) the `login` argument, (2) the `MCP_MT5_LOGIN` environment variable, (3) the
account number MetaTrader already has saved as its current login (read from
`config/common.ini`'s `Login=` key — verified working end-to-end). Set `MCP_MT5_LOGIN`
explicitly only if you have multiple saved accounts and the terminal's current one isn't the
one you want used. **The account's password is never read, stored, or passed by this
server** — it relies entirely on MetaTrader's own saved/remembered credentials for that
login. Never pass a password through an MCP tool call.

**First backtest for a new symbol/date range may need a retry.** Verified on a fresh demo
account: the Strategy Tester downloads missing history from the broker in the background,
but its own internal timeout for that (~18s) can be shorter than one authentication
round-trip on a fresh connection, causing the first attempt to fail with "no history data"
even though the download is actually still happening (visible as growing `.hcc` files under
`bases/<server>/history/<symbol>/`). Simply calling `run_backtest` again against the same
symbol/range once it's downloaded resolves it.

## Environment variables

| Variable | Purpose |
|---|---|
| `MCP_MT5_INSTALL_DIR` | Pin the MT5 install directory if more than one is found |
| `MCP_MT5_LOGIN` | Account number for Strategy Tester runs (see above) |
| `MCP_MT5_COMPILE_TIMEOUT_MS` | Compile timeout (default 120000) |
| `MCP_MT5_BACKTEST_TIMEOUT_MS` | Backtest timeout (default 600000) |

## Tools

| Tool | Purpose |
|---|---|
| `get_environment_info` | Resolve/re-resolve the MT5 install + data folder |
| `list_files` | List files/dirs under the MQL5 sandbox |
| `read_file` | Read a source file |
| `write_file` | Create/overwrite a source file |
| `delete_file` | Delete a single file |
| `compile` | Compile via MetaEditor CLI, parsed errors/warnings + `.ex5` path |
| `run_backtest` | Run the Strategy Tester, parsed performance metrics |
| `get_journal` | Read the MQL5 journal log |

## Development

```bash
npm test                # unit tests (sandbox, log parser, ini builder, report parser)
npm run dry-run -- env  # exercise modules directly, no MCP client needed
npm run smoke-test      # write -> compile -> (backtest if MCP_MT5_LOGIN set) -> cleanup
npm run dev             # run the server directly with tsx, for local iteration
```

## Verified end-to-end

Both `compile` and `run_backtest` have been run for real against a live MetaTrader 5
installation (build 6182) with a demo account, through the actual MCP server over stdio, not
just their underlying modules:

- `compile`'s log format (`src/compile/logParser.ts`) was verified against real
  `MetaEditor64.exe /log` output, including a clean compile and one with an error and a
  warning — see `test/logParser.test.ts` for the captured fixture. Exit codes were confirmed
  unreliable (one run exited 1 with zero errors, another exited 0 with a real error), which
  is why success is derived only from the parsed log plus a freshly-written `.ex5`.
- `run_backtest`'s report parsing (`src/backtest/reportParser.ts`) was verified against a
  real Strategy Tester report. Two bugs surfaced only through this real run and are now
  fixed: `Expert=` needs Windows backslashes (a forward-slash value is silently ignored, and
  the terminal falls back to whichever EA it last remembers running — no error at all), and
  the report is written directly to the data folder root rather than under `Tester/` as
  might be assumed (it's now parsed there, then moved into the sandboxed `Files/.mcp/`
  scratch dir so repeated runs don't litter your live MetaTrader data folder). The real
  report's labels matched `LABEL_MAP`'s guesses exactly for this build; if a different
  build/locale doesn't, the result's `raw` field always carries every parsed label/value pair
  regardless, so nothing is silently lost — extend `LABEL_MAP` from there if needed.