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

• 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! 🌟

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.
• Vector DB Integration: Query an embedded vector database with MSX resources for development support.
• Hybrid Mode: This MCP server supports hybrid access mode (STDIO and HTTP transports).

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.

• 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.

• 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, searchBytes.
• debug_vram: VRAM operations: getBlock, readByte, writeByte, searchBytes.
• debug_breakpoints: Breakpoint management: create, remove, list.

• 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.

• vector_db_query: Query the Vector DB resources to obtain information about MSX systems, cartridges, and other development resources.
• msxdocs_resource_get: Retrieve MCP resources for MCP clients that don't support 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.

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

• 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.

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

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.

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

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

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"
      }
    }
  }
}

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

npm install -g @nataliapc/mcp-openmsx

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 MCP_HTTP_PORT=3000
export MCP_ALLOWED_ORIGINS="http://localhost,http://mydomain.com"

mcp-openmsx

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

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

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

npm run dev

GPL2 License - see LICENSE file for details.

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

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

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