Gearboy MCP Server: Setup for Claude Code, Codex and Other Apps

• Loads a Game Boy ROM into the emulator

  Opens a ROM file you point to, resets the emulator and loads its symbols. Anything you had in the debugger may be lost.

  Try: “Load /roms/pokemon_red.gb and tell me its mapper.”

  Write · load_media

• Shows the loaded ROM's title, mapper and sizes

  Reports the ROM path, title, cartridge type, mapper, ROM and RAM size and whether it uses Color or Super Game Boy features.

  Try: “What cartridge type is the loaded game?”

  Read · get_media_info

• Lists ROMs you opened recently

  Returns the recent ROM list with the file paths that load_media accepts.

  Try: “What ROMs did I open recently?”

  Read · list_recent_media

• Pauses the game and opens the debugger

  Stops execution at the current instruction so you can inspect it.

  Try: “Pause the game right now.”

  Write · debug_pause

• Resumes the game

  Resumes running after a pause or a breakpoint.

  Try: “Continue until the next breakpoint.”

  Write · debug_continue

• Runs one CPU instruction

  Executes the next instruction and goes inside any subroutine call.

  Try: “Step one instruction and show me the registers.”

  Write · debug_step_into

• Runs one instruction without entering calls

  Executes the next instruction and treats a call as a single step.

  Try: “Step over this call.”

  Write · debug_step_over

• Runs until the current routine returns

  Keeps running until the return instruction of the current subroutine.

  Try: “Step out of this function.”

  Write · debug_step_out

• Runs one or more video frames

  Advances the emulation by whole frames up to the vertical blank. It can wait for the frames to finish or return at once.

  Try: “Advance 10 frames.”

  Write · debug_step_frame

• Resets the emulated console

  Restarts the emulated Game Boy or Game Boy Color.

  Try: “Reset the console.”

  Write · debug_reset

• Shows whether the game is paused and where

  Reports whether the debugger is paused, which breakpoint was hit and the current program counter.

  Try: “Is the game paused, and where?”

  Read · debug_get_status

• Runs until a chosen address

  Continues execution until the code reaches the address you give.

  Try: “Run to address 0x0150.”

  Write · debug_run_to_cursor

• Stops the game at an address

  Adds a breakpoint on ROM or RAM, video memory or I/O registers. Code addresses break on execute, video and I/O addresses on read or write.

  Try: “Set a breakpoint at 0x0150 in bank 1.”

  Write · set_breakpoint

• Stops the game anywhere in an address range

  Adds one breakpoint that covers a span of addresses instead of a single one.

  Try: “Break on any write to 0xC000-0xC0FF.”

  Write · set_breakpoint_range

• Removes a breakpoint

  Deletes the breakpoint that matches the address, end address and memory area you give.

  Try: “Remove the breakpoint at 0x0150.”

  Write · remove_breakpoint

• Lists all breakpoints

  Shows every execute, read and write breakpoint now set.

  Try: “List my breakpoints.”

  Read · list_breakpoints

• Turns interrupt breakpoints on or off

  Switches breakpoints for the VBlank, LCD STAT, timer, serial and joypad interrupts.

  Try: “Break on every VBlank interrupt.”

  Write · toggle_irq_breakpoints

• Lists the console's memory regions

  Returns the areas such as ROM banks, video RAM, work RAM, sprite memory and I/O, with sizes and IDs to use in other calls.

  Try: “What memory areas can I read?”

  Read · list_memory_areas

• Reads bytes from a memory region

  Returns bytes from a memory area by its zero-based offset.

  Try: “Read 16 bytes of WRAM at offset 0.”

  Read · read_memory

• Writes bytes into memory

  Overwrites bytes in a memory area and skips the hardware side effects a real write would have. It changes the running game.

  Try: “Write 0xFF to WRAM offset 0x10.”

  Write · write_memory

• Changes a CPU register

  Sets one of AF, BC, DE, HL, SP or PC, or an 8-bit part of them.

  Try: “Set register A to 0x10.”

  Write · write_cpu_register

• Shows readable code around an address

  Returns the disassembly the emulator has recorded, with bank, mnemonic and bytes. Code appears only after it has run.

  Try: “Disassemble around the current PC.”

  Read · get_disassembly

• Reads the CPU registers and flags

  Returns AF, BC, DE, HL, SP, PC, the Z, N, H and C flags, interrupt state, halt state, speed and bank.

  Try: “What are the CPU registers right now?”

  Read · get_cpu_status

• Reads the screen chip registers

  Returns LCDC, STAT, scroll and window positions, line counters, DMA, palettes and the Color-only registers.

  Try: “Show the LCD registers.”

  Read · get_lcd_registers

• Shows the screen's current mode and line

  Reports the LCD mode, line counters and whether the VBlank and STAT interrupts are on.

  Try: “Which scanline is the LCD on?”

  Read · get_lcd_status

• Reads the sound chip state

  Returns the state of the square, wave and noise channels, including volume, frequency, envelope and wave RAM.

  Try: “Which sound channels are playing?”

  Read · get_apu_status

• Reads the link-cable port state

  Reports the serial registers, interrupt, timing and local link-cable diagnostics.

  Try: “Show the serial port status.”

  Read · get_serial_status

• Clears link-cable counters

  Resets the link-cable transport counters for sync, waits and recovery.

  Try: “Reset the link cable counters.”

  Write · reset_link_cable_metrics

• Takes a screenshot of the game

  Captures the current frame as a PNG the assistant can look at.

  Try: “Take a screenshot and describe what is on screen.”

  Read · get_screenshot

• Starts recording video and audio to a file

  Records the emulated video and audio to an AVI file on your disk until you stop it.

  Try: “Record the next 10 seconds to /tmp/run.avi.”

  Write · start_video_recording

• Stops the recording

  Finishes the AVI file and returns its path and frame count.

  Try: “Stop recording.”

  Write · stop_video_recording

• Loads a symbol file for readable labels

  Appends labels from a .sym file (bank:address name) to the symbol table.

  Try: “Load /project/game.sym.”

  Write · load_symbols

• Lists the five save-state slots

  Shows each slot with its ROM name, time and whether it has a screenshot.

  Try: “Which save slots are used?”

  Read · list_save_state_slots

• Picks the active save slot

  Chooses slot 1 to 5 for the next save or load.

  Try: “Use save slot 3.”

  Write · select_save_state_slot

• Saves the game to the active slot

  Writes the emulator state to the selected slot.

  Try: “Save the game now.”

  Write · save_state

• Restores the game from the active slot

  Loads the saved state from the selected slot and replaces the current one.

  Try: “Load the saved state.”

  Write · load_state

• Saves the game to a file you name

  Writes the emulator state to the path you give.

  Try: “Save state to /tmp/before-boss.state.”

  Write · save_state_file

• Restores the game from a file

  Loads an emulator state from the path you give.

  Try: “Load state from /tmp/before-boss.state.”

  Write · load_state_file

• Sets the fast-forward speed

  Chooses one of five speeds from 1.5x up to unlimited.

  Try: “Set fast-forward to 3x.”

  Write · set_fast_forward_speed

• Turns fast-forward on or off

  Switches fast-forward at the speed already set.

  Try: “Turn fast-forward on.”

  Write · toggle_fast_forward

• Shows how much rewind history exists

  Reports whether rewind is on, how many snapshots are held and how many seconds they cover.

  Try: “How far back can I rewind?”

  Read · get_rewind_status

• Jumps back to a rewind snapshot

  Loads the snapshot with the number you give. The emulator must be paused first.

  Try: “Rewind to snapshot 20.”

  Write · rewind_seek

• Presses a Game Boy button

  Presses, releases or taps up, down, left, right, A, B, Start or Select.

  Try: “Press Start, then tap A.”

  Write · controller_button

• Plays a timed button sequence

  Runs a list of taps, presses, releases and waits counted in frames.

  Try: “Walk right for 30 frames, then press A.”

  Write · controller_macro

• Shows which buttons are held

  Reports the buttons that count as pressed now and any taps waiting to release.

  Try: “Which buttons are pressed?”

  Read · get_input_state

• Lists the 40 on-screen sprites

  Returns position, tile, attributes and Color palette and bank for each of the 40 sprites in sprite memory.

  Try: “List the sprites near the top of the screen.”

  Read · list_sprites

• Captures one sprite as an image

  Returns a single sprite as a PNG.

  Try: “Show me sprite 5.”

  Read · get_sprite_image

• Bookmarks a code address

  Saves a bookmark in the disassembler at a logical address.

  Try: “Bookmark the game's main loop at 0x0150.”

  Write · add_disassembler_bookmark

• Removes a code bookmark

  Deletes a disassembler bookmark at an address.

  Try: “Remove the bookmark at 0x0150.”

  Write · remove_disassembler_bookmark

• Lists code bookmarks

  Shows all disassembler bookmarks.

  Try: “List my code bookmarks.”

  Read · list_disassembler_bookmarks

• Names an address

  Adds a label for a bank and address in the disassembler.

  Try: “Label 0x0150 as MainLoop.”

  Write · add_symbol

• Removes a label

  Deletes the label at a bank and address.

  Try: “Remove the label at 0x0150.”

  Write · remove_symbol

• Lists all labels

  Shows every label in the symbol table.

  Try: “List all symbols.”

  Read · list_symbols

• Finds a label by name

  Looks up an exact symbol name and returns every match.

  Try: “Where is MainLoop?”

  Read · lookup_symbol_by_name

• Finds the label at an address

  Returns the symbol, if any, at a bank and address.

  Try: “What is at 0x0150?”

  Read · lookup_symbol_at_address

• Shows the current call chain

  Lists the subroutine calls that led to the current instruction.

  Try: “Show the call stack.”

  Read · get_call_stack

• Selects a span in the memory editor

  Marks a range by area and zero-based offsets, for tools that act on the selection.

  Try: “Select WRAM 0x100 to 0x1FF.”

  Write · select_memory_range

• Reads the current memory selection

  Returns the range selected for an area.

  Try: “What range is selected?”

  Read · get_memory_selection

• Fills the selected memory with one value

  Writes the same byte over the whole selection. Select a range first.

  Try: “Fill the selection with 0x00.”

  Write · set_memory_selection_value

• Bookmarks a memory address

  Saves a bookmark at an area offset.

  Try: “Bookmark WRAM offset 0x10.”

  Write · add_memory_bookmark

• Removes a memory bookmark

  Deletes the bookmark at an area offset.

  Try: “Remove that memory bookmark.”

  Write · remove_memory_bookmark

• Lists memory bookmarks

  Shows the bookmarks for a memory area.

  Try: “List WRAM bookmarks.”

  Read · list_memory_bookmarks

• Watches a memory address

  Adds a watch at an area offset with optional notes and bit size.

  Try: “Watch the player HP at WRAM 0x10.”

  Write · add_memory_watch

• Removes a memory watch

  Deletes the watch at an area offset.

  Try: “Stop watching WRAM 0x10.”

  Write · remove_memory_watch

• Lists memory watches

  Shows the watches set for a memory area.

  Try: “List my watches.”

  Read · list_memory_watches

• Takes a memory snapshot for a search

  Stores a snapshot of an area so a later search can find values that changed.

  Try: “Snapshot WRAM before I take damage.”

  Write · memory_search_capture

• Finds memory values that changed

  Compares memory against a snapshot, a fixed value or an address, which helps find where a game keeps its lives or health.

  Try: “Which bytes decreased since the snapshot?”

  Read · memory_search

• Finds bytes or text in memory

  Searches for a run of hex bytes or text and returns the addresses.

  Try: “Find the text "GAME OVER" in memory.”

  Read · memory_find

• Reads the CPU trace

  Returns recorded instructions and hardware events such as screen, input, timer, sound, serial and mapper events.

  Try: “Show the last 50 trace entries.”

  Read · get_trace_log

• Controls the CPU trace

  Turns tracing on or off, to memory or to disk, and sets its capacity, file limit, output folder and event filters.

  Try: “Trace to disk in /tmp/trace for 5 seconds.”

  Write · set_trace_log

• Starts, stops or resets the profiler

  Starts the function profiler (it opens the Profiler window), stops it or clears it. It collects data only while running.

  Try: “Start the profiler.”

  Write · set_profiler

• Reads profiler results

  Returns call counts, calls per frame and cycle totals for each function.

  Try: “Which function uses the most cycles?”

  Read · get_profiler_data

• Reads Super Game Boy state

  Reports Super Game Boy mode, multiplayer, last command, border animation, palettes and attributes.

  Try: “Is Super Game Boy mode active?”

  Read · get_sgb_status

• Lists cheat codes

  Shows each cheat with its code, description and whether it is on and valid.

  Try: “List my cheats.”

  Read · list_cheats

• Adds a cheat code

  Adds an enabled Game Genie or GameShark code. Join several with plus signs.

  Try: “Add GameShark 01FF16C1.”

  Write · add_cheat

• Removes a cheat

  Deletes a cheat by its index from the cheat list.

  Try: “Remove cheat 0.”

  Write · remove_cheat

Watch out for

• Older versions exposed HTTP on all interfaces

  Advisory GHSA-fmvx-487g-mrww says the HTTP mode bound all interfaces without authentication before 3.8.7. Use 3.8.7 or later; the current release is 3.8.20. github.com

• It can change the running game

  Memory writes, register writes, cheats, save-state loads and button presses all change the emulated game. Use a throwaway ROM session or save a state first. github.com

• HTTP mode can be shared on your network

  The default HTTP address is 127.0.0.1. Binding to another address needs a bearer token, and all connected clients control the same emulator. github.com

• It can write files you name

  Video recording, trace to disk and save-state-to-file write to paths the assistant chooses. Check the path before approving. github.com

Security advisories