McxBMCView

mcxBMCView is an open-source tool for deterministic screenshot capture, keyboard input, and remote BIOS reflashing on servers with AMI MegaRAC BMC (Baseboard Management Controller) HTML5 consoles. Built with Playwright (headless Chromium) for scriptable, AI-agent-compatible server management without requiring a human browser session.

Published by MagnaCapax (Pulsed Media) under the Apache-2.0 license.

Repository: github.com/MagnaCapax/mcxBMCView

Tools

mcxBMCView provides three standalone tools:

Tool	Purpose	Output
getscreen	Captures the server's physical display as a JPEG via the BMC's HTML5 KVM viewer	Screenshot file path on stdout; exit 0 (success) or 1 (failure)
sendkeys	Types keyboard input into the server console — login sequences, BIOS navigation, boot menus	Exit 0/1
flashbios	Reflashes BIOS firmware via the BMC's SPI bus — works even when the host CPU is dead (no POST, no screen)	Prints `BIOS_FLASH_OK` on success; exit 0/1

How it works

AMI MegaRAC BMCs serve the KVM viewer as an HTML5 Single Page Application (SPA). No server-side screenshot API exists on this firmware. mcxBMCView drives headless Chromium (via Playwright) through the full BMC authentication and KVM session flow:

Navigates to the BMC login page
Authenticates via the web form
Waits for the SPA to populate sessionStorage (~6 seconds)
Opens the KVM viewer via window.open()
The viewer establishes a WebSocket session using the ASPEED video compression engine
Captures the viewport, dispatches keyboard events, or drives the BIOS update page
Cleans up: stops the KVM stream, closes the viewer, deletes the API session

API-based login with cookie injection does not work — the WebSocket handshake validates session state that only the full SPA login flow establishes correctly. This was discovered through five failed authentication approaches during development.

Why Playwright (not IPMI commands)

Standard IPMI tools (ipmitool) provide power control, sensor reading, and Serial over LAN — but they cannot capture the graphical console, navigate BIOS setup screens, or trigger firmware updates through the web UI. The BMC REST API on some firmware versions (notably AMI MegaRAC 1.80) returns "Invalid API Call" for management endpoints, making the web UI the only path for operations like BIOS reflash.

AI agent integration

mcxBMCView was designed specifically for integration into automated server management loops:

Deterministic output: Screenshot path on stdout, debug information on stderr
Simple exit codes: 0 for success, 1 for failure — composable into shell scripts and orchestrators
Stateless invocations: Each call creates and cleans up its own BMC session
Vision model loop: Capture screen → feed to vision LLM → determine next action → send keystrokes → repeat

Debug mode is available via the BMC_DEBUG=1 environment variable.

BIOS flash

The flashbios tool drives the BMC web UI's Maintenance → BIOS Update page. The ASPEED BMC chip writes directly to the SPI flash chip on its own power domain, independent of the host CPU. This means BIOS can be reflashed even when the CPU is completely dead (no POST, no screen output).

Flash modes:

immediate — flash BIOS without power action (best when CPU is already non-functional)
next_boot — stage firmware, flash on next boot
shutdown — flash after graceful shutdown

A typical 32 MB BIOS ROM flash takes approximately 2 minutes.

Compatibility

Board	BMC Firmware	Status
ASRock Rack EPYCD8-2T	2.20.00	Tested, working
ASRock Rack X570D4I-2T	1.80	Tested, working
ASRock Rack (various other models)	1.10, 1.24	Tested, working
Gigabyte AMI MegaRAC boards	Various	Expected to work (same firmware family)

Not compatible: Supermicro IPMI, Dell iDRAC, HP iLO — these use entirely different web interfaces and authentication flows.

Requirements

Node.js >= 18.0.0
Playwright ^1.50.0 (installs its own Chromium, ~250 MB)
System libraries for headless Chromium: npx playwright install-deps chromium on Debian/Ubuntu

No other dependencies. Single npm install to set up.

Limitations

~25 seconds per operation (inherent to browser automation + BMC session setup)
Single active KVM session at a time (BMC hardware limitation)
AMI MegaRAC only — other BMC vendors use incompatible web interfaces
Self-signed TLS certificates (certificate validation is disabled, as BMCs universally use self-signed certs)
BMCs allow approximately 4–5 concurrent web sessions; exhausted sessions produce blank screenshots. Recovery: ipmitool mc reset cold

Origin

mcxBMCView was developed by Pulsed Media during production server recovery incidents where standard IPMI tools were insufficient. The BIOS flash capability was battle-tested on a server that would not POST after a routine reboot — after IPMI power cycling failed repeatedly over 12+ hours, the BIOS was successfully reflashed remotely using the tool, recovering the server without a datacenter visit.

The tool went through 4 iterations of the flash workflow before achieving reliable end-to-end BIOS reflashing:

Iteration	Problem
v1	Wrong hash route: `bios-update` vs `bios_update`
v2	Uploaded ROM to hidden `file_PublicKey` input instead of visible `fileBIOS_image`
v3	Did not detect/click the "Proceed" button after upload reached 100%
v4	Success — full flow in a single session