mt4ctl 0.1.0

MCP server for managing headless MetaTrader terminals over SSH (Wine + systemd)

mt4ctl

An MCP server for operating headless MetaTrader terminals — over SSH, from your agent.

Manage MetaTrader 4 terminals running under Wine + systemd on remote hosts (native Linux or WSL2) entirely through the Model Context Protocol: check status, read logs, capture screenshots, control the systemd lifecycle, and perform the tricky headless first-login — all as clean, typed tools.

---

Why

Algo traders increasingly run MetaTrader 4 headless on Linux — Wine under Xvfb, supervised by systemd, no GUI. That's great for uptime and terrible for day-to-day operations: every "is it connected?", "restart that one", or "log this new account in" turns into a fragile chain of ssh → (Windows cmd → wsl) → bash → systemctl → wine, with quoting hazards at every hop.

mt4ctl collapses that chain into a handful of MCP tools. Point it at a registry of your hosts and terminals, wire it into Claude (or any MCP client), and operate the whole farm conversationally:

"Which demo terminals are down?" · "Restart demo2." · "Log demo2 into account 1000002 on ExampleBroker-Demo." · "Screenshot the live terminal so I can see the AutoTrading state."

Quickstart (5 minutes)

mt4_list works offline (no SSH/MT4 needed), so you can confirm the wiring before anything else lines up:

# 1. create a minimal registry
mkdir -p ~/.config/mt4ctl
cat > ~/.config/mt4ctl/terminals.yaml <<'YAML'
hosts:
  box: { ssh: my-ssh-alias, kind: native }
terminals:
  t1: { host: box, service: mt4-t1, data_dir: /home/trader/mt4/t1, account: "1000001" }
YAML

# 2. add to Claude Code (uvx runs the server straight from git — no install)
claude mcp add --scope user mt4ctl \
  --env MT4CTL_CONFIG="$HOME/.config/mt4ctl/terminals.yaml" \
  -- uvx --from git+https://github.com/ak40u/mt4ctl mt4ctl

Then ask Claude: "Use mt4_list to show my configured terminals." You should see your t1 row. Once the SSH alias and systemd unit line up, ask for "mt4_status t1". Full setup and other clients are below.

Features

• Per-terminal connection detection — attributes established broker sockets to each terminal's systemd cgroup, so terminals sharing a host (and a Wine prefix) are reported independently — not guessed from a host-wide count.
• Headless first-login — automates the one-time bootstrap a migrated terminal needs (MetaTrader's saved password is machine-bound), then hands control back to systemd for automatic reconnection on every restart.
• Native and WSL2 hosts — one registry, two execution models; commands are base64-shipped so nothing breaks in the cmd.exe → wsl.exe → bash gauntlet.
• Live-trading guardrails — terminals tagged env: live reject mutating operations unless you pass confirm=true.
• Concurrent status — hosts are polled in parallel via asyncio.
• Secrets stay secret — passwords resolve from arg → env → secrets file, are never logged, and the transient remote login config is shred-ed after use.

How it works

┌────────────┐   MCP/stdio   ┌──────────────────┐
│ MCP client │ ────────────► │     mt4ctl       │
│ (Claude…)  │               │  FastMCP server  │
└────────────┘               └────────┬─────────┘
                                       │ asyncio SSH (base64-framed)
                 ┌─────────────────────┼─────────────────────┐
                 ▼                                           ▼
        ┌─────────────────┐                        ┌──────────────────┐
        │  native Linux   │                        │  Windows + WSL2  │
        │  sudo systemctl │                        │  wsl -u root --  │
        ├─────────────────┤                        ├──────────────────┤
        │ mt4-live-main…  │  systemd units running │ mt4-demo1…       │
        │ wine terminal.exe (Xvfb display)         │ wine terminal.exe│
        └─────────────────┘                        └──────────────────┘

A thin, typed core (models → config → ssh → scripts → operations/login) sits under the server adapter, so the logic is testable without a network and the MCP layer stays a one-line-per-tool shell.

Install

The fastest path needs no clone and no global install — uv runs mt4ctl straight from the repo and fetches a matching Python itself:

uvx --from git+https://github.com/ak40u/mt4ctl mt4ctl   # runs the stdio server

No uv yet? curl -LsSf https://astral.sh/uv/install.sh | sh — or skip it and use the pipx path below.

Prefer a persistent mt4ctl command? Install it with uv or pipx:

uv tool install git+https://github.com/ak40u/mt4ctl
# or
pipx install git+https://github.com/ak40u/mt4ctl

For development:

git clone https://github.com/ak40u/mt4ctl.git && cd mt4ctl
python -m venv venv && source venv/bin/activate
pip install -e ".[dev]"

The server machine needs either uv or Python 3.11+, plus SSH access to your hosts. The remote hosts need the usual tools mt4ctl shells out to: systemctl, ss, getent, and (for screenshots) imagemagick/scrot + xdotool.

Configure

Copy the example registry and fill in your real hosts and terminals:

mkdir -p ~/.config/mt4ctl
cp examples/terminals.example.yaml ~/.config/mt4ctl/terminals.yaml

The registry is resolved from MT4CTL_CONFIG, then ~/.config/mt4ctl/terminals.yaml, then ./terminals.yaml. See examples/terminals.example.yaml for the full schema and docs/configuration.md for details.

Keep your populated registry private. It maps your accounts and infrastructure. The default .gitignore excludes terminals.yaml.

Connect to an MCP client

Claude Code — one command wires it up (user scope = available in every project):

claude mcp add --scope user mt4ctl \
  --env MT4CTL_CONFIG="$HOME/.config/mt4ctl/terminals.yaml" \
  -- uvx --from git+https://github.com/ak40u/mt4ctl mt4ctl

Or commit a project .mcp.json to share with a team (Claude Code expands ${HOME}):

{
  "mcpServers": {
    "mt4ctl": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/ak40u/mt4ctl", "mt4ctl"],
      "env": { "MT4CTL_CONFIG": "${HOME}/.config/mt4ctl/terminals.yaml" }
    }
  }
}

Claude Desktop — Settings → Developer → Edit Config (claude_desktop_config.json), same shape but use an absolute config path (Desktop does not expand ${HOME}), and an absolute command path if uvx is not on the GUI app's PATH (which uvx):

{
  "mcpServers": {
    "mt4ctl": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/ak40u/mt4ctl", "mt4ctl"],
      "env": { "MT4CTL_CONFIG": "/Users/you/.config/mt4ctl/terminals.yaml" }
    }
  }
}

Installed mt4ctl persistently (uv/pipx)? Replace command/args with just "command": "mt4ctl".

Tools

Tool	Mutates	Description
mt4_list	–	List configured terminals (offline).
mt4_status	–	Per-terminal service state + broker connection + log age.
mt4_logs	–	Tail / grep a terminal's newest log file.
mt4_screenshot	–	Capture a terminal window as PNG.
mt4_control	✓	start / stop / restart a unit (live needs confirm).
mt4_login	✓	One-time headless login for auto-reconnect (live needs confirm).

Full reference: docs/tools.md.

Security

• Mutations on env: live terminals require explicit confirm=true.
• Credentials resolve from argument → MT4CTL_PASSWORD_<account> → secrets file; they are never written to logs and the transient remote login config is shredded after use.
• All remote execution goes through your existing SSH config and key-based auth; mt4ctl stores no credentials of its own.
• During mt4_login the password is embedded in the base64-framed script handed to ssh, so it is briefly visible in the local process list to your own user. On the remote side it is written only to a fresh mktemp config (mode 600) that a cleanup trap shreds on any exit path. On POSIX, the local secrets file is rejected if it is readable by group/other.

Development

ruff check src tests      # lint
mypy                      # type-check (strict)
pytest                    # tests

See docs/architecture.md for the module boundaries.

License

MIT © Pavel Volkov. See LICENSE.