mcp-openmsx

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.

Installation

Run this command in your terminal to add the MCP server to Claude Code.

Run in terminal:

View docs

Command

claude mcp add --transport stdio nataliapc-mcp-openmsx npx -y @nataliapc/mcp-openmsx \
  --env OPENMSX_PATH="path/to/openmsx (if required)" \
  --env MCP_LOG_LEVEL="info" \
  --env OPENMSX_CONFIG="default or path to openMSX config"

How to use

mcp-openmsx is an MCP server that bridges AI-driven intent with the openMSX emulator. It exposes a rich set of MCP Tools to control the emulator, manage media, inspect memory, debug CPU/VDP, and automate workflows. The server translates high-level natural language commands from an AI Copilot into TCL commands that drive openMSX, enabling automation for testing, debugging, and development of MSX software. You can use emulator control tools to launch and manage openMSX instances, use media tools to insert ROMs or disks, and leverage debugging and automation utilities to script complex scenarios or reproduce issues. The integration with a Vector DB-enabled toolset allows querying MSX resources and embedding documentation into your automation flows. The server supports both stdio and HTTP transports for MCP clients in hybrid mode.

How to install

Prerequisites:

Node.js (LTS recommended) and npm installed on your system
Access to a shell/terminal
Optional: openMSX emulator installed if you want local control (path configurable)

Step-by-step installation:

Install Node.js and npm from https://nodejs.org or via your package manager.
Install the MCP OpenMSX package from npm (the command below uses npx to fetch and run the package): npx -y @nataliapc/mcp-openmsx

This will install and start the MCP server CLI as part of the run flow. If you prefer a local install, you can install globally or as a project dependency: npm install @nataliapc/mcp-openmsx --save
Configure and run the server using the generated configuration or your preferred MCP client.
Ensure environment variables are set if your setup requires specific paths for openMSX or credentials for resources.

Optional:

If you plan to run via a container, you can adapt the npm-based start into a container entrypoint and expose the MCP transport ports as needed.

Additional notes

Notes and tips:

The MCP server translates AI-driven commands into TCL sequences for openMSX. Ensure your Copilot or AI client can emit compatible MCP commands.
You can customize env vars like OPENMSX_PATH and OPENMSX_CONFIG to point to your local openMSX installation or config file.
If you encounter transport or handshake issues, verify that the MCP client and server agree on the stdio or HTTP transport and the port configuration.
If running in CI or headless environments, consider enabling headless/openMSX modes and redirecting logs to files for easier debugging.
Typical issues include missing openMSX binaries, misconfigured paths, or insufficient permissions to launch emulator processes. Check logs for TCL translation errors or TCL command availability.

Related MCP Servers

mcp-tool-filter

Ultra-fast semantic tool filtering for MCP (Model Context Protocol) servers using embedding similarity. Reduce your tool context from 1000+ tools down to the most relevant 10-20 tools in under 10ms.