Skip to main content
Glama

mcp-openmsx

by nataliapc
GitHub
GPL 2.0
18
OverviewInspectNewSchemaRelated ServersReviewsScore
Need Help?View Source CodeReport Issue

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: PAYPAL Link

Table of Contents

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

Architecture

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

Automation Tools

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

Documentation Tools

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

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:

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.
{ "servers": { "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.

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

VariableDescriptionDefault ValueExample
OPENMSX_EXECUTABLEPath or command to the openMSX executableopenmsx/usr/local/bin/openmsx
OPENMSX_SHARE_DIRDirectory containing openMSX data files (machines, extensions, etc.)System dependent/home/myuser/.openmsx/share
OPENMSX_SCREENSHOT_DIRDirectory where screenshots will be savedDefault for openmsx/myproject/screenshots
OPENMSX_SCREENDUMP_DIRDirectory where screen dumps will be savedDefault for openmsx/myproject/screendumps
OPENMSX_REPLAYS_DIRDirectory where replay files will be savedDefault for openmsx/myproject/replays
MCP_TRANSPORTTransport mode (stdio or http)stdiohttp
MCP_HTTP_PORTPort number for HTTP transport mode30008080

Advanced Manual Usage

Important


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

Currently, the MCP server requires Linux to be compiled. It has not been tested on Windows or macOS, although it will likely work on the latter as well.

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 MCP_HTTP_PORT=3000

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.

This server cannot be installed

-
security - not tested
A
license - permissive license
-
quality - not tested

How are these scores calculated?

hybrid server

The server is able to function both locally and remotely, depending on the configuration or use case.

This MCP provides comprehensive tools and resources for MSX software development, testing, and automation through openMSX emulator.

  1. Table of Contents
    1. Project Overview
      1. Architecture
        1. Available MCP Tools
          1. Emulator Control Tools
          2. Programming Tools
          3. Debugging Tools
          4. Automation Tools
          5. Documentation Tools
        2. Available MCP Resources
          1. What are MCP Resources?
          2. Available Resources
          3. Resources from:
        3. Quick Start
          1. Quick installation with VSCode
          2. STDIO mode (recommended)
          3. Streamed HTTP mode (more advanced)
          4. Basic Installation with Claude Desktop
          5. Environment Variables
        4. Advanced Manual Usage
          1. Manual installation
          2. Manual set of Environment Variables
          3. As MCP Server (stdio)
          4. As HTTP Server
        5. Development
          1. Prerequisites to build
          2. Building
          3. Running in Development
        6. License
          1. Support
            1. Contributing

              Related MCP Servers

              • MCP Toolbox for Databases

                googleapis
                -
                security
                A
                license
                -
                quality
                Open source MCP server specializing in easy, fast, and secure tools for Databases.
                Last updated -
                9,080
                Go
                Apache 2.0
                • Linux

              • Xbox Controller MCP Server

                bcperry
                -
                security
                A
                license
                -
                quality
                An MCP server that provides Xbox controller emulation capabilities, allowing users to programmatically control buttons, analog sticks, and triggers through an API interface.
                Last updated -
                Python
                MIT License
                • Linux

              • MCPX MCP Gateway

                TheLunarCompany
                -
                security
                A
                license
                -
                quality
                MCPX is a remote-first MCP aggregator that enables zero-code integration, unified access, and dynamic routing across multiple MCP servers. It offers tool-level access controls, usage visibility, and customization to streamline and secure agentic workflows.
                Last updated -
                263
                Go
                MIT License

              View all related MCP servers

              New MCP Servers

              MCP directory API

              We provide all the information about MCP servers via our MCP API.

              curl -X GET 'https://glama.ai/api/mcp/v1/servers/nataliapc/mcp-openmsx'

              If you have feedback or need assistance with the MCP directory API, please join our Discord server