MCP-openMSX

MCP-openMSX

"Orchestrating a binary opera where AI conducts, MCP interprets, and openMSX acts as the 8-bit diva."

A Model Context Protocol (MCP) server for automating openMSX emulator instances.

This server provides comprehensive tools for MSX software development, testing, and automation through standardized MCP protocols.

🎁🎁 If you find this project useful, please consider making a donation by PAYPAL Link or GitHub Sponsors

---

Table of Contents

• Project overview
• Architecture
• Available MCP Tools
• Available MCP Resources
• ⚡ Quick Start
  • Quick installation with VSCode
  • Basic installation with Claude Desktop
  • Environment Variables
• Advanced manual usage
• Development
• License
• Support
• Contributing
• 🌟 More stars! 🌟

Project Overview

This project creates a bridge between modern AI-assisted development (e.g. GitHub Copilot, Claude Desktop) and retro computing (MSX systems) by providing:

• Emulator Control: Launch, configure, manage openMSX instances, and replay timelines.
• Media Management: Handle ROM cartridges, floppy disks, and cassette tapes.
• BASIC Programming Support: Tools to facilitate BASIC language programming and development.
• Debugging Tools: Full CPU debugging with breakpoints, memory inspection, and step execution.
• Video Control: VDP register manipulation and screen capture.
• Memory Operations: Read/write RAM, VRAM, and I/O port access.
• Automation: Keyboard input simulation and savestate management.
• Hybrid Documentation Search: Query an embedded local index of MSX resources combining semantic (multilingual embeddings) and keyword (BM25) search, runs fully offline.
• Hybrid Mode: This MCP server supports hybrid access mode (STDIO and HTTP transports).

Architecture

flowchart TB
  %%{init: {'flowchart': {'curve':'monotoneX' }}}%%

  subgraph yourComputerGroup[" "]
    HOST["Your AI dev companion<br>(MCP Client support)"]
    EMU["openMSX emulator<br>(local instance)"]

    subgraph mcpGroup["**mcp-openmsx**"]
      MCP["MCP Server<br>stdio / http"]
      TOOLS["MCP Tools"]
      VECTORDB[("Embeddings RAG<br>(Vector Database)")]
      RESOURCES["MCP Resources"]
      LOCALDATA["Local data<br>(inner documentation)"]
    end
    EXTDATA["External data<br>(webpages)"]

    HOST <--"_MCP<br>&nbsp;protocol&nbsp;_"--> MCP
    MCP <--> TOOLS & RESOURCES
    TOOLS <--"_&nbsp;Query&nbsp;_"--> VECTORDB
    TOOLS <--"_&nbsp;Console commands&nbsp;_"---> EMU
    RESOURCES <--_&nbsp;http&nbsp;_---> EXTDATA
    RESOURCES <--> LOCALDATA
  end

  HOST@{ shape: rounded }
  MCP@{ shape: rounded }
  EMU@{ shape: rounded }
  LOCALDATA@{ shape: docs }
  EXTDATA@{ shape: docs }
  style yourComputerGroup color:#fff,fill:#4444,text-align:left
  style mcpGroup color:#fff,fill:#4444
  style HOST color:#000000,fill:#BBDEFB,stroke-width:4px,stroke-dasharray:0
  style MCP color:#000000,fill:#FFF9C4
  style EMU color:#FFFFFF,fill:#0000FF,stroke-width:4px,stroke-dasharray:0

The MCP server translates high-level natural language commands from your Copilot AI into TCL commands to control openMSX, enabling automated MSX software testing and debugging.

Available MCP Tools

Emulator Control 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 informacion 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.

Programming Tools

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

Debugging Tools

• 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, writeBlock, searchBytes.
• debug_vram: VRAM operations: getBlock, readByte, writeByte, searchBytes.
• debug_breakpoints: Breakpoint management: create, remove, list.
• debug_log: Debug log: log, read.
• debug_conditions: Condition management (like breakpoints, but not tied to an address — a Tcl expression evaluated continuously while the CPU runs): create, remove, list.

Automation Tools

• emu_keyboard: Send text or key combinations to emulator: sendText, sendKeyCombo.
• 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.

Documentation Tools

• vector_db_query: Hybrid search (semantic embeddings + BM25) over the local MSX documentation index, for information about MSX systems, cartridges, programming, and other development resources.
• msxdocs_resource_get: Retrieve MCP resources for MCP clients that don't support MCP resources.

Optional Advanced Tools

• openmsx_tcl_cmd: Executes a native Tcl command in the connected openMSX instance. It is disabled by default and is registered only when the user sets OPENMSX_ENABLE_RAW_TCL=true. Existing typed tools remain available and are preferred for operations they cover.

Available MCP Resources

What are MCP Resources?

MCP resources are structured data sets, documentation, and helper files that extend the capabilities of the MCP server. They provide essential information such as machine definitions, extension lists, media templates, and programming examples, enabling more powerful automation, testing, and development workflows for MSX software within the MCP-openMSX environment.

Available Resources

There are more than 60 resources available, some included directly in the MCP and others accessible via download when queried. They are organized into the following categories:

• Processors (Z80, R800)
• Bios (Bios ROM, DOS ROM, SUBROM, ...)
• System
• Audio
• Video
• Programming (ASM, BASIC, ...)
• MSX-DOS
• MSX-UNAPI
• MSX BASIC

And books and manuals:

• MSX2 Technical Handbook
• The MSX Red Book
• SDCC Compiler

Resources from:

• Grauw MSX Assembly Page
• Z80 Heaven Wiki
• The MSX Red Book
• MSX2 Technical Handbook
• Konamiman MSX-UNAPI-specification
• BiFi MSX Net
• MRC Wiki
• MSX Banzai!
• SDCC

Thanks to the authors of these resources, who have made them available under various licenses. This MCP server includes some of these resources to enhance the development experience.

Important

The rights to these resources belong to their respective authors and are distributed under the licenses they have defined.

Quick Start

You can use this MCP server in this basic way with the precompiled NPM package.

Quick installation with VSCode

Steps to install the MCP server in VSCode:

1. Install Github Copilot extension
2. Install nodejs (npx command must be available in your PATH).
3. Install de MCP Server:
   • Use the Install MCP Server button above to install the MCP server in your VSCode settings.
   • Or add to your workspace folder a file named .vscode/mcp.json with the json configuration below.

STDIO mode (recommended)

{
  "servers": {
    "mcp-openmsx": {
      "command": "npx",
      "args": ["@nataliapc/mcp-openmsx"],
      "env": {
        "OPENMSX_SHARE_DIR": "C:\\the\\location\\of\\your\\openmsx\\share\\folder"
      }
    }
  }
}

Note

In Windows you can change the command field to npx.cmd if you experience permission issues.

Note

Environment variables are optional. Customize them as you need.

Streamed HTTP mode (more advanced)

{
  "servers": {
    "mcp-openmsx": {
      "type": "http",
      "url": "http://localhost:3000/mcp",
      "headers": { }
    }
  }
}

Note

The MCP HTTP Server must be running standalone in the same computer or in another (make run_http).

Basic Installation with Claude Desktop

Follow these instrutions to access Claude's claude_desktop_config.json file.

Edit it to include the following JSON entry:

{
  "mcpServers": {
    "mcp-openmsx": {
      "command": "npx",
      "args": ["@nataliapc/mcp-openmsx"],
      "env": {
        "OPENMSX_SHARE_DIR": "C:\\the\\location\\of\\your\\openmsx\\share\\folder"
      }
    }
  }
}

Note

Environment variables are optional. Customize them as you need.

Environment Variables

Variable	Description	Default Value	Example
OPENMSX_EXECUTABLE	Path or command to the openMSX executable	Auto-detected: openmsx (Linux), /Applications/openMSX.app/Contents/MacOS/openmsx (macOS), openmsx.exe (Windows)	/usr/local/bin/openmsx or C:\Program Files\openMSX\openmsx.exe
OPENMSX_SHARE_DIR	Directory containing openMSX data files (machines, extensions, etc.)	System dependent	/home/myuser/.openmsx/share
OPENMSX_SCREENSHOT_DIR	Directory where screenshots will be saved	Default for openmsx	/myproject/screenshots
OPENMSX_SCREENDUMP_DIR	Directory where screen dumps will be saved	Default for openmsx	/myproject/screendumps
OPENMSX_REPLAYS_DIR	Directory where replay files will be saved	Default for openmsx	/myproject/replays
OPENMSX_ENABLE_RAW_TCL	Register the optional openmsx_tcl_cmd native Tcl tool. This grants the MCP client powerful access to openMSX and potentially the host filesystem; enable it only when explicitly required.	false	true
OPENMSX_LAUNCH_HEADLESS	Launch openMSX without a renderer window (headless mode). Sets renderer to none instead of the default SDLGL-PP at startup. Useful for CI, testing, and server-side environments.	false	true
MCP_TRANSPORT	Transport mode (stdio or http)	stdio	http
MCP_HTTP_PORT	Port number for HTTP transport mode	3000	8080
MCP_ALLOWED_ORIGINS	Comma-separated list of allowed origins for HTTP transport	Empty for all allowed	http://localhost,http://mydomain.com
OPENMSX_WINDOWS_CONTROL	Windows only. How the server talks to openMSX's control socket (see below)	stdio-proxy	direct-sspi
OPENMSX_WINDOWS_PROXY_EXECUTABLE	Windows only. Override path to the SSPI proxy helper (development)	Bundled bin/win-x64/mcp-openmsx-sspi-proxy.exe	C:\path\to\mcp-openmsx-sspi-proxy.exe
OPENMSX_MODELS_CACHE	Directory where the embedding model is cached (also honors HF_HOME / TRANSFORMERS_CACHE)	~/.cache/mcp-openmsx	/opt/models
OPENMSX_EMBED_PROVIDER	Index generator only. cuda uses the GPU (fp32 model) to regenerate the index, falling back to CPU if CUDA is unavailable. The MCP server itself always uses CPU/int8 and ignores this variable.	(generator: cpu)	cuda

Native Tcl command tool (OPENMSX_ENABLE_RAW_TCL)

The optional openmsx_tcl_cmd tool provides direct access to openMSX's native Tcl console for advanced or version-specific functionality not covered by the typed tools. It can use the runtime self-documentation commands help, about, openmsx_info, and machine_info before executing unfamiliar commands.

The tool is not registered by default. Only the user should enable it in the MCP server configuration:

{
  "env": {
    "OPENMSX_ENABLE_RAW_TCL": "true"
  }
}

Direct Tcl is intentionally unrestricted and may modify emulator state, access files, load scripts, or terminate openMSX. Treat it as equivalent to granting the MCP client local command execution privileges. Restart the MCP server after changing the setting.

Documentation search model

The vector_db_query tool runs a local hybrid search (semantic embeddings + BM25). The embedding model (multilingual-e5-small, ONNX quantized, ~118 MB, 512-token context, multilingual) is downloaded once from the HuggingFace Hub on the first query and cached on disk (see OPENMSX_MODELS_CACHE above). After that it runs fully offline. No API key is required. To pre-populate the cache for air-gapped environments, run one query on a networked machine and copy the cache directory.

Regenerating the index (rare) embeds the whole corpus. On CPU this is slow; on an NVIDIA GPU set OPENMSX_EMBED_PROVIDER=cuda for the generator to use it (requires CUDA 13 runtime libraries + cuDNN 9), which is ~50× faster. The GPU path uses the larger fp32 model; the server keeps using the int8 model and the two are interchangeable for search (same ranking). End users never download the fp32 model.

Windows control modes (OPENMSX_WINDOWS_CONTROL)

On Windows, openMSX is a GUI app whose TCP control socket requires SSPI (Negotiate/NTLM) authentication. The server supports several transports:

Value	Description
stdio-proxy	Default. Launches a self-contained .NET helper that performs SSPI and exposes a clean XML stdio channel — the most robust path.
direct-sspi	Authenticates from Node via the optional node-expose-sspi package. Fallback / debugging.
socket	Legacy alias of direct-sspi.

Linux and macOS are unaffected (openmsx -control stdio).

The bundled proxy is built from helpers/openmsx-sspi-proxy and can be rebuilt reproducibly from Linux with Docker (no local .NET required):

cd mcp-server
pnpm build:proxy:win-x64:docker   # → bin/win-x64/mcp-openmsx-sspi-proxy.exe

Advanced Manual Usage

Important

This is not needed for using the MCP server, but if you want to install it manually, follow these steps.

The MCP server runs on Linux, macOS, and Windows. Building from source requires Node.js >= 18 and TypeScript.

Manual installation

npm install -g @nataliapc/mcp-openmsx

Manual set of Environment Variables

Set optional environment variables to customize the server:

export OPENMSX_EXECUTABLE="openmsx"
export OPENMSX_SHARE_DIR="/usr/share/openmsx"
export OPENMSX_SCREENSHOT_DIR="/my_project/screenshots"
export OPENMSX_SCREENDUMP_DIR="/my_project/screendumps"
export OPENMSX_REPLAYS_DIR="/my_project/replays"
export OPENMSX_ENABLE_RAW_TCL="true"
export OPENMSX_LAUNCH_HEADLESS="true"
export MCP_HTTP_PORT=3000
export MCP_ALLOWED_ORIGINS="http://localhost,http://mydomain.com"

As MCP Server (stdio)

mcp-openmsx

As HTTP Server

MCP_TRANSPORT=http mcp-openmsx
# or
mcp-openmsx http

Development

Important

This is not needed for using the MCP server, but if you want to contribute or modify the code, follow these steps.

Prerequisites to build

• Node.js >= 18.0.0
• TypeScript
• openMSX emulator installed

Building

git clone https://github.com/nataliapc/mcp-openmsx.git
cd mcp-openmsx/mcp-server
npm install
npm run build

Running in Development

npm run dev

License

GPL2 License - see LICENSE file for details.

Support

If you need help, or have questions or suggestions, please open an issue on the GitHub Issues page or check the project discussions.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

More stars!

Please give us a star on GitHub if you like this project.

Star History

---