windows98-mcp

Control a real Windows 98 VM through 47 explicit Model Context Protocol (MCP) tools. Agents can take screenshots, use exact mouse and keyboard input, run and stream commands, manage windows and processes, use the clipboard, and transfer files and directories without relying on Computer Use for ordinary VM work.

Download the latest Windows 98 guest · SHA-256 · All releases · npm package

The GitHub repository is private, so release links require an account that can access it. The npm package is public.

How it works

WIN98CTL.EXE is a C89 Windows 98 guest agent. It maintains an authenticated outbound TCP connection to a TypeScript broker on the host-only VM network. Every MCP client connects to the singleton broker through a local named pipe. The broker provides exclusive leases so two agents cannot control the same VM at the same time.

Guest traffic is integrity-protected with HMAC-SHA256 but is not encrypted. Use an isolated host-only network and never expose the guest listener publicly.

Requirements

• Node.js 22.17 or newer on the host.
• Windows 98 Second Edition with Winsock 2 in a VM.
• A VMware/VirtualBox host-only adapter shared by the host and guest.
• The host-only IPv4 address of the host and the IPv4 address assigned to the Windows 98 guest.

The verified development setup uses host 192.168.60.1 and guest 192.168.60.128 on a /24 host-only network.

Quick start

Download and extract the latest Windows 98 guest ZIP on the host. Then, from the workspace that agents may access, generate the matching host config and WIN98CTL.INI inside that extracted release folder:

npx -y windows98-mcp@latest configure `
  --bind 192.168.60.1 `
  --ip 192.168.60.128 `
  --guest-dir "C:\Downloads\windows98-mcp-guest"

This creates two matching local configurations:

• .win98-mcp/config.json in the current workspace: broker bind address, expected guest IP, random PSK, allowed host root, and state location.
• WIN98CTL.INI in the extracted guest folder: host address, port, identity, and the same PSK. Running configure again reuses the existing PSK.

Copy the complete configured release folder to C:\WIN98CTL in Windows 98. Then:

1. Run RUNTEST.BAT.

2. If it reports PASS, run WIN98CTL.EXE and leave its small status window open.

3. On the host, verify the connection:

   npx -y windows98-mcp@latest doctor --ip 192.168.60.128
   npx -y windows98-mcp@latest smoke-test --ip 192.168.60.128
   

4. After the smoke test passes, run INSTALL.BAT in Windows 98 to start the guest agent at login.

The guest retries every two seconds forever when the broker is offline or restarted.

MCP client configuration

Running the package without a subcommand starts the stdio MCP adapter. --ip is the expected Windows 98 guest source IP; the guest still connects outbound to the host address stored in WIN98CTL.INI.

Codex project configuration (.codex/config.toml):

[mcp_servers.win98]
command = "npx"
args = ["-y", "windows98-mcp@latest", "--ip", "192.168.60.128"]
cwd = 'C:\path\to\your\workspace'
startup_timeout_sec = 20
tool_timeout_sec = 1860
required = false

Generic MCP JSON configuration:

{
  "mcpServers": {
    "win98": {
      "command": "npx",
      "args": [
        "-y",
        "windows98-mcp@latest",
        "--ip",
        "192.168.60.128"
      ],
      "cwd": "C:\\path\\to\\your\\workspace"
    }
  }
}

The configured cwd must contain the .win98-mcp/config.json generated by configure, or set WIN98_MCP_CONFIG to an absolute config path.

CLI

windows98-mcp [command] [options]

broker              Run the long-lived singleton broker
stdio               Run the stdio MCP adapter (the default)
configure           Match the host config to a downloaded guest release
doctor              Check the broker, guest, and capabilities
simulator           Run the deterministic simulated guest
smoke-test          Exercise a connected guest inside C:\MCPTEST
diagnostics [dir]   Collect sanitized diagnostics

--ip <guest-ip>     Accept only this Windows 98 guest IPv4 address
--bind <host-ip>    Override the host-only listener address
--port <port>       Override TCP port 9898
--config <file>     Use a specific broker config
--state-dir <dir>   Override logs/artifacts state directory
--host-root <dir>   Add an allowed host transfer root (repeatable)

configure additionally requires --guest-dir <extracted-release-folder>.

Equivalent environment variables include WIN98_MCP_GUEST_IP, WIN98_MCP_BIND_HOST, WIN98_MCP_GUEST_PORT, WIN98_MCP_CONFIG, WIN98_MCP_STATE_DIR, WIN98_MCP_HOST_ROOTS, and WIN98_MCP_PSK.

MCP tools

The tool groups are:

• Lease and status: vm_status, vm_capabilities, vm_lock, vm_wait, vm_unlock.
• Screen and input: screen_capture, eight mouse tools, five keyboard tools, and input_batch.
• Desktop: clipboard get/set plus window list, focus, close, and capture.
• Commands: one-shot shell execution and cursor-based interactive terminal sessions.
• System and files: processes, filesystem primitives, resumable file transfer, and merging directory transfer.

The first VM-affecting tool atomically acquires the lease. Status calls do not. Every operational result reminds the caller that the VM remains locked and must be released with vm_unlock. Inactive leases expire after 30 minutes; disconnect cleanup also releases held keys, buttons, terminals, and transfers.

Development

npm ci
npm run typecheck
npm test
npm run build
npm audit --audit-level=moderate

# Build the real Windows 98 guest with pinned Open Watcom 1.9
powershell -File scripts/bootstrap-openwatcom.ps1 -Install
powershell -File scripts/build-guest.ps1 -Clean
powershell -File scripts/stage-release.ps1

The test suite includes deterministic protocol, broker, MCP, lease, transfer, artifact, and input tests. The guest build audits the PE32 GUI subsystem (4.0) and permits imports only from Windows 98 system DLLs.

Limitations

Windows 98 has no ConPTY, so terminals use redirected pipes rather than a true full-screen console. DOS/TUI screens, boot failures, BSODs, kernel hangs, and exclusive graphics surfaces remain outside the guest agent. File transfers are limited to 2 GiB minus one byte, and unrepresentable ANSI/keyboard characters are rejected instead of silently substituted.

License

MIT