Gearsystem MCP
A Sega Master System, Game Gear and SG-1000 emulator with an MCP server: the agent sets breakpoints and reads memory
- 400 ★ on the repository
- Last commit
- GPL-3.0
Broad access
Why this level
- The client launches the local emulator executable, and the agent writes to console memory, loads ROMs and save states from given paths and writes video and logs to disk
- In HTTP mode on a non-loopback address emulator control opens up over the network, which is why the server demands a token
Install
- Works in
Manual install
brew install --cask drhelius/geardome/gearsystemFor macOS. If Homebrew asks you to trust the third-party tap, run brew trust --tap drhelius/geardome. On other systems download a build from the releases.
Access and checks
How we reviewBroad accessThe tool can change data, run commands or handle secrets.
- The client launches the local emulator executable, and the agent writes to console memory, loads ROMs and save states from given paths and writes video and logs to disk
- In HTTP mode on a non-loopback address emulator control opens up over the network, which is why the server demands a token
This is third-party code. Review the repository files before installing.
What it does
Gearsystem is a C++ emulator for the Sega Master System, Game Gear and SG-1000 consoles with a graphical debugger. The MCP server is built into the emulator itself and runs beside its window: the agent and the human see one state, and changes made through MCP show up in the interface at once. The agent gets the whole debugger: pause and single-step on the Z80, registers, reading and writing several memory areas, disassembly, breakpoints on execution, reads and writes, a call stack, symbols, bookmarks and watches. Separate tools show the VDP video processor, the PSG and YM2413 sound chips and all 64 sprites. The agent can also take a screenshot, record video to AVI and press controller buttons. The set includes tracing of CPU, VDP, input, sound and mapper events, a function profiler with call counts and cycles, rewind and save state slots. Memory search stores a snapshot, compares it after an action in the game and finds variables such as lives or score. The repository carries two agent skills: one for debugging and tracing, one for translations, cheats and ROM hacks.
Who it is for. For developers of Sega Master System, Game Gear and SG-1000 games and for anyone studying or reworking old ROMs: translations, cheats, algorithm analysis.
Good fit when
- A game draws corrupted graphics and you need to inspect the VDP registers, VRAM contents and the sprite attribute table
- You need to find the VBlank interrupt handler and label the subroutines it calls with symbols
- You want to find the lives or score variable in memory and build a cheat through snapshot-based search
- You want to know which game functions burn the most cycles per frame, and the profiler will give numbers
- A bug report needs a screenshot or an AVI recording of a few hundred frames
Not a fit when
- You need an emulator for a different console: Gearsystem covers only the Master System, Game Gear and SG-1000
- Several agents must work with one emulator instance at the same time: they share state and get in each other's way
- You cannot run a native executable on the machine: the server is the emulator itself, started locally by the client
Example request
Load the ROM /path/to/game.sms, find the VBlank interrupt handler, label the subroutines it calls with symbols and explain what it doesMCP
- Transport
- stdio, http
- Authentication
- not required
Environment variables
GEARSYSTEM_MCP_HTTP_TOKENsecret- Bearer token for HTTP mode. Required when binding to a non-loopback address, otherwise the server refuses to start.
Limitations
The MCP server is part of the application, and there is no separate npm or PyPI package. The emulator installs with brew install --cask drhelius/geardome/gearsystem on macOS, from a PPA or RPM on Linux, or as a build from the releases page. Claude Desktop has ready MCPB extensions for Windows, macOS and Linux on x64 and ARM64. Windows may need the Visual C++ Redistributable and the OpenGL Compatibility Pack. While the MCP server runs, the emulator does not pause when the window loses focus, even with Pause When Inactive enabled. In windowless mode screenshots take their settings from the Debug menu, so set them in the graphical interface beforehand. The license is GPL-3.0. Supply your own ROM file. Screenshots and debug results return to the MCP client and may enter its model context.
How to disable. Remove the gearsystem entry from the client configuration: in Claude Code run claude mcp remove gearsystem, in VS Code delete the block from .vscode/mcp.json, in Claude Desktop remove the extension in the Extensions section of Settings or the entry in claude_desktop_config.json. Delete the gearsystem-debugging and gearsystem-romhacking skill folders from the agent's skills directory. The emulator itself can stay as an ordinary application.
FAQ
How do I connect Gearsystem to Claude Code?
Run claude mcp add --transport stdio gearsystem -- /path/to/gearsystem --mcp-stdio with the path to the executable and check claude mcp list. The MCP client launches the emulator using this configuration; then load your own ROM with load_media.
How does Gearsystem's stdio mode differ from HTTP?
In stdio mode the client launches the emulator and talks to it over input and output pipes, and this mode is recommended. In HTTP mode you start the emulator by hand with gearsystem --mcp-http, it listens on 127.0.0.1:7777/mcp, and the client connects to the running process. The --mcp-http-port flag changes the port.
How do I cut the number of Gearsystem tools in the agent's context?
Start the emulator with the --mcp-router flag. Then 12 frequent tools stay direct, including load_media, read_memory, set_breakpoint and get_screenshot, and the rest are called through search_tools, get_tool_info and execute_tool.
Can I debug with Gearsystem without a window?
Yes, use `--headless` with `--mcp-stdio` or `--mcp-http`. Give independent HTTP sessions separate ports. With `--portable`, use separate application copies in different directories because settings are stored beside the executable.
How do I find the lives variable address in a Master System game?
Take a snapshot with memory_search_capture, lose a life in the game and run memory_search with a comparison operator, for example less than the previous value. Repeat the comparison to narrow down candidate addresses. The gearsystem-romhacking skill describes this loop.
Discussion
No questions or reviews yet.
Related
MCP serversA Game Boy emulator with a debugger and a built-in MCP server: the agent controls execution, reads memory and inspects hardware state
The Geargrafx emulator built-in MCP server: an agent debugs PC Engine games, inspects memory and sets breakpoints.
A local code graph and context toolkit for agents: entities, Git relations and recorded mistakes served via CLI, hooks and MCP
The summer-engine package links an agent to the Summer game engine: MCP server, game-dev skills and a CLI to build and publish.
Context Engine: code search and memory for an agent
Context Engine
A skill that teaches an agent to query the Context Engine code index and symbol graph before reading files directly
Universal Modder
universal-modder
A plugin and skills for mods to games on your PC: engine recon, code analysis, fal assets, testing in the running game and a showcase video
Comparison with similar tools
Cards that share the main search query, and how they differ.
| Tool | Official | Authentication | Repository stars | Main difference |
|---|---|---|---|---|
| Gearsystem (this card) | no | not required | 400 | |
| Gearboy | yes | not required | 1,221 | a Game Boy emulator by the same author with a similar MCP debugger |
| GhidrAssistMCP | no | not required | 810 | static binary analysis in Ghidra: pseudocode and call graphs without running the game |
README in short
Release 3.9.24 provides MCPB bundles for Windows, macOS and Linux on x64 and ARM64. Main-branch documentation changes independently of releases, so check new commands against the installed build. Debugging and ROM-hacking skills add instructions to the emulator.