MCP OpenMSX Server

You can use this MCP server to automate and control openMSX emulator instances, enabling AI-assisted development, testing, and debugging of MSX software with standardized MCP commands. It translates high-level prompts into precise emulator actions, media management, debugging, and automation workflows in a hybrid STDIO and HTTP setup.

How to use

You interact with the MCP server from your MCP client or AI companion. Start the local or remote MCP server, then issue MCP commands to launch and configure openMSX, insert media, control the VDP, run BASIC programs, set breakpoints, inspect memory, and capture screenshots. The server exposes a broad set of tools that cover emulator control, programming, debugging, automation, and vector resources. Use the HTTP transport for remote control or the STDIO transport for local usage, depending on your environment.

How to install

Prerequisites: you need Node.js available in your environment and an openMSX installation with its data files. Install the MCP server using the STDIO path for local usage or set up the HTTP server for remote access.

{
  "servers": {
    "mcp_openmsx_http": {
      "type": "http",
      "url": "http://localhost:3000/mcp",
      "args": []
    },
    "mcp_openmsx_stdio": {
      "command": "npx",
      "args": ["@nataliapc/mcp-openmsx"],
      "env": {
        "OPENMSX_SHARE_DIR": "/path/to/openmsx/share"
      }
    }
  }
}

Additional setup notes

Environment variables are optional but allow you to customize the server behavior. The following variables are commonly used when starting the server in STDIO mode to point to your openMSX data and output directories.

OPENMSX_EXECUTABLE=/path/to/openmsx
OPENMSX_SHARE_DIR=/path/to/openmsx/share
OPENMSX_SCREENSHOT_DIR=/path/to/screenshots
OPENMSX_SCREENDUMP_DIR=/path/to/screendumps
OPENMSX_REPLAYS_DIR=/path/to/replays
MCP_HTTP_PORT=3000

Available tools

emu_control

Controls an openMSX emulator: launch, close, powerOn, powerOff, reset, getEmulatorSpeed, setEmulatorSpeed, machineList, extensionList, wait.

emu_replay

Controls emulation timeline: start, stop, status, goBack, absoluteGoto, advanceFrame, reverseFrame, truncate, saveReplay, loadReplay.

emu_info

Obtain information about the current emulated machine: getStatus, getSlotsMap, getIOPortsMap.

emu_media

Manage ROM, disk, and tape media: tapeInsert, tapeRewind, tapeEject, romInsert, romEject, diskInsert, diskInsertFolder, diskEject.

emu_vdp

Manage VDP (Video Display Processor): getPalette, getRegisters, getRegisterValue, setRegisterValue, screenGetMode, screenGetFullText.

basic_programming

BASIC tools: isBasicAvailable, newProgram, runProgram, setProgram, getFullProgram, getFullProgramAdvanced, listProgramLines, deleteProgramLines.

debug_run

Control execution: break, isBreaked, continue, stepIn, stepOut, stepOver, stepBack, runTo.

debug_cpu

Read/write CPU registers, CPU info, Stack pile, and Disassemble code: getCpuRegisters, getRegister, setRegister, getStackPile, disassemble, getActiveCpu.

debug_memory

RAM memory operations: selectedSlots, getBlock, readByte, readWord, writeByte, writeWord, advanced_basic_listing.

debug_vram

VRAM operations: getBlock, readByte, writeByte.

debug_breakpoints

Breakpoint management: create, remove, list.

emu_keyboard

Send text input to emulator: sendText.

emu_savestates

Save and restore machine states: load, save, list.

screen_shot

Capture emulator screen: as_image, to_file.

screen_dump

Export screen data as BASIC BSAVE instruction.

msxdocs_resource_get

Retrieve MCP resources for MCP clients that don’t support MCP resources.

vector_db_query

Query the Vector DB to obtain information about MSX systems, cartridges, and other development resources.