mcp-openmsx-usage

Original：🇺🇸 English

Translated

Use this skill to learn using mcp-openmsx tools to control and automate the openMSX emulator, or when interacting with the openMSX emulator for develop/test/debug workflows or interactions that require direct control or information retrieval. Covers all MCP tools. Do NOT use for general agent tasks or when no direct openMSX interaction is required.

2installs

Sourcenataliapc/mcp-openmsx

Added on2026-03-28

NPX Install

npx skill4agent add nataliapc/mcp-openmsx mcp-openmsx-usage

SKILL.md Content

View Translation Comparison →

MCP-OpenMSX Usage Guide

Skill usage

Read this file completely.
Read the linked files if topic/description is relevant to your task. Always load reference files if there is even a small chance the content may be required. It's better to have the context than to miss a pattern or make a mistake.

Overview

mcp-openmsx

is an MCP server that bridges AI assistants with the openMSX MSX emulator. It spawns openMSX, sending TCL commands via STDIO or HTTP transports.

Typical workflow: launch emulator → insert media → interact (keyboard/BASIC/debug) → capture screen → close.

Prerequisites

Using

mcp-openmsx

in

stdio

mode requires:

```
npx
```
installed.
```
openMSX emulator
```
installed and accessible via
```
$PATH
```
or set
```
OPENMSX_EXECUTABLE
```
env.
```
mcp-openmsx
```
installed
.
Set
```
OPENMSX_SHARE_DIR
```
env if auto-detection fails or custom folder is needed.

Skill Index

MCP Configuration: How to configure the MCP server, including transport selection (stdio vs HTTP), emulator executable path, and share directory settings.
Environment Variables
MCP tools reference:
1. Emulator Control: Manage emulator state (launch, power, reset), media (tapes, ROMs, disks), machine info, keyboard input, savestates, and time-travel replay.
2. VDP (Video Display Processor): Inspect and modify VDP state, including registers, palette, screen mode, and text content.
3. Screen Capture: Capture screenshots, and screen memory dumps from the emulator.
4. Debugging: Control execution (break, continue, step), inspect CPU registers, RAM, and VRAM, manage breakpoints.
5. BASIC Programming: Write, load, run, and manage BASIC programs on the emulator.
6. Documentation & Search: Search and retrieve MSX technical documentation from the embedded vector database and resource library to support development tasks.
MCP Resources: Extensive collection of MSX documentation resources and reference materials embedded in the MCP vector database, organized by category and topic for easy retrieval.
MCP Prompts: Custom MCP prompts for generating structured reference materials based on the embedded documentation resources, such as an MSX BASIC instruction manual page.
Tips & Best Practices

Workflows reference files and guides

Detailed step-by-step guides for common workflows. ALWAYS load reference files if there is even a small chance the content may be required. It's better to have the context than to miss a pattern or make a mistake. Read the relevant file when needed:

MSX documentation search workflow — Search and retrieve MSX technical documentation from the embedded vector database and resource library to support development tasks.
Launch and configure an MSX machine — Discover machines/extensions, launch, wait for boot, verify status, speed control, power cycle.
Programming in MSX BASIC — Write, load, run, verify, and manage BASIC programs. Includes line management, interrupting, and loading large programs.
Debugging the VDP — Inspect/modify VDP registers, palette, VRAM, screen modes. Includes sprite debugging and screen corruption analysis workflows.
Debugging a BASIC program — Interrupt execution, inspect state, edit lines, low-level interpreter debugging, time-travel, infinite loop detection, variable inspection.
Debugging an ASM program — Breakpoints, stepping, register/memory inspection, disassembly, BIOS call verification, crash/hang analysis, locating functions without .sym files.
Debugging MSX-DOS programs — Correct breakpoint workflow for MSX-DOS disk-loaded programs. Avoids boot contamination (BIOS/DOS firing breakpoints before app starts). Includes hang detection and savestate checkpointing.
Working with media (ROM, disk, tape) — Insert/eject ROMs, disks, tapes. Development workflows for each media type.
Time-travel debugging with replay and savestates — Timeline navigation, frame-by-frame stepping, checkpointing, comparing execution paths.
Screen capture and visual verification — Screenshots (inline/file), screen dumps (MSX format), text reading, before/after comparison.

Tips & Best Practices

All addresses and values use hexadecimal format (e.g.
```
0x4000
```
,
```
0xA5
```
).
Always
```
emu_control.wait
```
a few seconds after
```
launch
```
to let the machine fully boot before interacting.
Use
```
screen_shot.as_image
```
to visually verify emulator state at any point.

Use

debug_run.break

before

emu_replay.goBack

or

absoluteGoto

to keep the timeline stable.

Use
```
vector_db_query
```
to search MSX documentation before relying on general knowledge.
Use
```
basic_programming
```
tools instead of
```
emu_keyboard.sendText
```
for BASIC development — they handle speed optimization and input encoding automatically.
Use
```
emu_savestates
```
to checkpoint progress during complex debugging sessions.
Addresses from
```
.sym
```
/
```
.map
```
files can be used directly with
```
debug_breakpoints.create
```
and
```
debug_run.runTo
```
.
MSX-DOS programs: never set breakpoints before confirming the app is on screen — the BIOS/DOS boot fires them first. See Debugging MSX-DOS Programs.
CP437 character encoding is the nearest encoding for MSX international charmap, use it for text input/output. Be mindful of special characters.