gc-mcp
Server Configuration
Describes the environment variables required to run the server.
| Name | Required | Description | Default |
|---|---|---|---|
| GC_MCP_BBA_MODE | No | BBA mode: ipc, hle, xlink, tap, tapserver, or empty/none. | ipc |
| GC_MCP_DATA_DIR | No | Root for per-instance data and captures. | ~/.gc-mcp |
| GC_MCP_GPU_ACCEL | No | GPU acceleration mode: auto, none, software, vgl, vgl-egl, or vgl-glx. | auto |
| GC_MCP_HW_BBA_IP | No | Default BBA IP for a new hardware instance; the console's own IP, used to reach the Swiss netboot listener. | |
| GC_MCP_GPU_DEVICE | No | GPU DRM device path, e.g. /dev/dri/card2. | auto-detected |
| GC_MCP_NATIVE_RES | No | GameCube native framebuffer size as WxH, used for display/capture sizing. | 640x480 |
| GC_MCP_HW_BBA_PORT | No | Default Swiss netboot listener port. | 4242 |
| GC_MCP_VIDEO_BACKEND | No | Video backend: OGL, Vulkan, or Software Renderer. | OGL |
| GC_MCP_BBA_MAC_PREFIX | No | Must be 00:09:bf or 00:17:ab. | 00:09:bf |
| GC_MCP_DOLPHIN_BINARY | No | Dolphin executable. | dolphin-emu |
| GC_MCP_HW_CAPTURE_FPS | No | Default hardware capture frame rate. | 30 |
| GC_MCP_MEMORY_BACKEND | No | Memory backend: process_vm or dolphin_engine. | process_vm |
| GC_MCP_VGL_3D_DISPLAY | No | 3D X server display for VirtualGL's GLX back end, e.g. :0.0. | |
| GC_MCP_CAPTURE_BACKEND | No | Capture backend: auto, xvfb, or framedump. | auto |
| GC_MCP_HW_CAPTURE_FLUSH | No | Number of stale buffers flushed before reading a fresh frame on the OpenCV path. | 5 |
| GC_MCP_HW_CAPTURE_WIDTH | No | Default hardware capture width. | 640 |
| GC_MCP_HW_CAPTURE_DEVICE | No | Default capture device for real hardware instances. | /dev/video0 |
| GC_MCP_HW_CAPTURE_FORMAT | No | Default hardware capture pixel format, e.g. mjpg or yuyv. | mjpg |
| GC_MCP_HW_CAPTURE_HEIGHT | No | Default hardware capture height. | 480 |
| GC_MCP_HW_CAPTURE_WARMUP | No | Seconds to stream a cold device before grabbing a frame; 0 disables. | 5 |
| GC_MCP_HW_CAPTURE_WARMUP_TTL | No | Seconds a warmed device is trusted before it is warmed again. | 60 |
Instructions
Guidance the server publishes about itself, which clients place ahead of the tool catalog so the model reads it before choosing anything.
You are controlling GameCube targets. Each instance is either a Dolphin emulator running headless under Xvfb (dolphin:<id>) or a registered real GameCube console (gamecube-hw:<id>, see gc_hardware_register).
Efficiency and latency:
Input actions have real latency (a keystroke/tap reaches the game only on a later frame). Prefer batching: use gc_controller_sequence to press a run of buttons in a single atomic call instead of many gc_controller_press / gc_controller_release round-trips.
For analog menu navigation, use gc_controller_flick (the stick counterpart of gc_controller_press_once) to push the stick and return it to centre in one call.
Screen capture is slow and expensive (render + encode). Prefer doing several inputs blind (e.g. a whole menu-selection sequence) before re-checking the screen with gc_capture_screenshot. One capture per meaningful state change, not per button.
Memory:
GameCube is big-endian. When reading/writing memory with gc_memory_read_struct / gc_memory_write_struct, prefix the format with '>' (or '!'), e.g. ">12f" for a 3x4 float matrix.
Emulator control:
Use gc_dolphin_toggle_pause to pause (e.g. before inspecting memory), gc_dolphin_step_frame to advance one frame while paused, and gc_dolphin_save_state / gc_dolphin_load_state (slots 1-8) to checkpoint. gc_dolphin_save_state also copies the state file into the states folder (/states, or pass copy_dir) so it survives instance removal.
These are driven by Dolphin hotkeys injected via xdotool; they need the instance's X display and xdotool installed. gc_dolphin_freeze / gc_dolphin_unfreeze are a coarse OS-level pause fallback.
Use gc_log (optionally tail=/grep=) to inspect the instance's Dolphin log for crashes or ROM console output (OSReport).
IPL boot:
gc_instance_start(boot_ipl=True) boots the original GameCube IPL (disables 'Skip System Menu'), so the boot logo/menu plays before the disc. It only works for a GameCube disc ('.iso'/'.gcm') and only if the server has an IPL folder configured (see gc_server_info).
Real GameCube hardware:
Register a connected console with gc_hardware_register(capture_device=...). Screen capture is implemented via the 'v4l2' backend; ROM loading via Swiss's netboot listener; controller and memory operations are not yet supported. gc_capture_screenshot on a hardware instance grabs a frame from the capture device. Use gc_hardware_devices / gc_capture_backends to list available devices and pick one whose 'can_capture' is true (some nodes expose only UVC metadata and cannot produce a video stream).
ROM loading on real hardware:
The console runs a custom Swiss build with a netboot listener on TCP 4242 of its own BBA IP. Set that IP with gc_hardware_update(instance_id, bba_ip='') (it is stored on the hardware instance).
gc_rom_load(instance_id, rom_path) boots a ROM. For hardware the path must be a console-side path starting with 'sdc:/' (SD2SP2) or 'fsp:/' (the configured FSP file server), e.g. 'sdc:/games/Foo.iso'.
If the console is inside a game the netboot listener is down; gc_rom_load first tries to return to Swiss with the A+Z+START combo, which needs hardware button pressing (not implemented yet), so it raises 'not implemented' until then.
gc_rom_load on a Dolphin instance instead stops and relaunches it booting a host-side ROM path.
Capabilities
Features and capabilities supported by this server
Protocol revision2025-11-25
| Capability | Details |
|---|---|
| tools | {
"listChanged": false
} |
| prompts | {
"listChanged": false
} |
| resources | {
"subscribe": false,
"listChanged": false
} |
Tools
Functions exposed to the LLM to take actions
| Name | Description |
|---|---|
| gc_server_infoB | Return information about this gc-mcp server and its environment. |
| gc_gpu_infoA | Report GPU rendering diagnostics for this host. Useful for deciding whether a GameCube instance will render on a real GPU or
fall back to Mesa software (llvmpipe), and for diagnosing the |
| gc_platform_listA | List the platforms currently available to control. Includes each running Dolphin instance ( |
| gc_platform_capabilitiesB | Describe the capabilities of a platform.
|
| gc_instance_startA | Start a new Dolphin instance booting the given ROM/DOL/ELF. Args: instance_id: Unique id for the instance. rom_path: Path to a .iso/.gcm/.dol/.elf file. controller_ports: Which GameCube ports (0-3) get a controller (default [0]). bba_mode: Broadband Adapter mode: ipc, hle, xlink, tap, tapserver, modem, or None/empty to disable. bba_mac: MAC address for the BBA (must start with 00:09:bf or 00:17:ab). video_backend: OGL, Vulkan, Null, or Software Renderer. capture_backend: auto, xvfb, or framedump. memory_backend: process_vm or dolphin_engine. internal_resolution: 1x/2x/... internal resolution. native_resolution: GameCube native framebuffer "WxH" (default 640x480). gpu_accel: auto/none/software/vgl/vgl-egl/vgl-glx (default auto). extra_core: Extra Dolphin.ini [Core] overrides. boot_ipl: Boot the original GameCube IPL (disable "Skip System Menu"), so the boot logo/menu runs before the disc. Only meaningful for a GameCube disc ('.iso'/'.gcm'); requires the server to be configured with a GC_MCP_IPL_DIR folder containing /IPL.bin files (see gc_server_info). Errors if IPL boot is requested but no IPL folder/files are configured. info: Free-form description/annotation shown in list and status output. |
| gc_instance_listB | List all known instances and their status. |
| gc_instance_statusC | Get detailed status for one instance. |
| gc_instance_stopC | Stop a running Dolphin instance. |
| gc_instance_removeB | Stop and delete an instance and its data directory. |
| gc_hardware_devicesA | Probe the Video4Linux2 capture devices present on this host. A real GameCube registers one of these (e.g. |
| gc_hardware_registerA | Register a real GameCube hardware instance. A hardware instance represents a physical console that stays connected to
this host. It is permanently remembered (persisted to the server's data
dir) until it is explicitly removed with Args:
instance_id: Unique id for the hardware instance (e.g. |
| gc_hardware_updateB | Update a registered hardware instance's settings and persist them. Use this to set the console's |
| gc_hardware_listA | List all registered real GameCube hardware instances. |
| gc_hardware_statusC | Get detailed status for one hardware instance. |
| gc_hardware_removeA | Forget a registered hardware instance. This removes the instance from the persistent registry so it is no longer
remembered across server restarts. Use |
| gc_logA | Read this instance's Dolphin log file ( Useful for diagnosing crashes, OSReport output from the ROM, or emulator
warnings. |
| gc_capture_backendsA | List the available capture backends and how to use them. |
| gc_capture_configureB | Configure the capture backend of an instance (e.g. display, screen_size). For a real GameCube hardware instance, this updates the V4L2 capture device
/ resolution / format and persists the change. |
| gc_capture_screenshotB | Capture the current frame of an instance to a PNG. Returns the path to the saved PNG, and optionally base64-encoded image data. |
| gc_rom_loadA | Boot/load a ROM on an instance. This is the unified entry point for pointing a target at a game:
For hardware, set the console's IP with |
| gc_controller_pressA | Press (hold) a button on a GameCube controller port. Buttons: A, B, X, Y, Z, START, L, R, D_UP, D_DOWN, D_LEFT, D_RIGHT. Remember to call gc_controller_release (or use gc_controller_sequence). |
| gc_controller_releaseC | Release a button on a GameCube controller port. |
| gc_controller_press_onceA | Tap a button once: press, hold for hold_duration ms, then release. This is the recommended way to send a button press for agent use. It is a single atomic action — you do not need to pair gc_controller_press and gc_controller_release. The button is always released afterwards. hold_duration defaults to 200 ms. Pass a larger value to hold the button longer (e.g. to hold START through a loading screen). |
| gc_controller_flickA | Flick an analog stick: push to (x, y), hold, then return to centre. This is the analog counterpart to gc_controller_press_once — a single atomic action you can use for menu navigation (e.g. nudge the stick up/down to move a cursor) without pairing set_stick/reset calls. stick is 'main' or 'c'. x/y are in -1..1 (0,0 = centre). The stick is always returned to centre afterwards. hold_duration defaults to 200 ms. |
| gc_controller_set_stickB | Set a stick position (analog). stick is 'main' or 'c'. x/y are in -1..1 (0,0 = centre). |
| gc_controller_set_triggerC | Set an analog trigger value (0..1). trigger is 'L' or 'R'. |
| gc_controller_sequenceA | Run a timed input sequence. Each step is a dict: {"t": ms, "type": "press"|"release", "button": "A"} {"t": ms, "type": "stick", "stick": "main", "x": 0.0, "y": 1.0} {"t": ms, "type": "trigger", "trigger": "L", "value": 1.0} {"t": ms, "type": "wait"} {"t": ms, "type": "reset"} The sequence runs on a background thread. Use gc_controller_sequence_cancel to stop it. |
| gc_controller_sequence_cancelC | Cancel a running input sequence. |
| gc_controller_get_stateC | Return the current state of a GameCube controller port. |
| gc_controller_resetC | Reset a GameCube controller port to its neutral state. |
| gc_memory_readB | Read bytes from the emulated GameCube RAM. address is a Dolphin emulated address (e.g. 0x80000000 for the start of MEM1). Returns a hex string. Fails gracefully if memory is not available. |
| gc_memory_writeB | Write bytes to the emulated GameCube RAM. data is a hex string (e.g. "00010203"). address is a Dolphin emulated address. Fails gracefully if memory is not available. |
| gc_memory_read_structB | Read memory at
GameCube is big-endian, so include a byte-order prefix in The result |
| gc_memory_write_structB | Pack
Returns the number of bytes written. |
| gc_dolphin_toggle_pauseA | Toggle the emulator's pause state (Dolphin's Toggle Pause hotkey, F10). Use this to pause a game (e.g. before inspecting memory or screen), then
resume. When paused, This injects a keystroke into the instance's X display via |
| gc_dolphin_step_frameA | Advance exactly one frame when the emulator is paused. Sends Dolphin's Frame Advance hotkey. Unlike The instance config binds Frame Advance to |
| gc_dolphin_save_stateA | Save a save-state to Only slots 1-8 have a Dolphin default hotkey binding (see
After saving, the state file is copied into |
| gc_dolphin_load_stateB | Load a save-state from Only slots 1-8 have a Dolphin default hotkey binding (see
|
| gc_dolphin_freezeA | Hard-freeze the Dolphin process with SIGSTOP. This is a coarse OS-level pause that always works (no X display or xdotool
needed). It is not compatible with frame-advance (the process is suspended,
so it cannot process hotkeys); use |
| gc_dolphin_unfreezeA | Resume a frozen Dolphin process with SIGCONT. |
| gc_dolphin_config_getA | Read a single Dolphin.ini configuration value for an instance. This is Dolphin-only (real hardware has no such config). |
| gc_dolphin_config_setB | Set a single Dolphin.ini configuration value for an instance. Writes to the instance's Config/Dolphin.ini. This is Dolphin-only. |
| gc_dolphin_config_apply_profileB | Apply a whole Dolphin.ini profile (a dict of section -> {key: value}). This is Dolphin-only. Existing keys in the same section are preserved unless overridden by the profile. |
| gc_dolphin_hotkey_getA | Read a Dolphin emulator hotkey binding.
|
| gc_dolphin_hotkey_setA | Set (or clear) a Dolphin emulator hotkey binding.
Dolphin loads Common keys (see |
Prompts
Interactive templates invoked by user choice
| Name | Description |
|---|---|
No prompts | |
Resources
Contextual data attached and managed by the client
| Name | Description |
|---|---|
No resources | |
TDQS
Scored across 45 tools
Most tools target a distinct resource+action (memory_read vs memory_write_struct, controller_press vs set_stick, hardware_register vs hardware_update). A few pairs overlap: gc_instance_start vs gc_rom_load (both boot a ROM), gc_platform_list vs gc_instance_list, gc_dolphin_freeze/unfreeze vs gc_dolphin_toggle_pause, and gc_capture_configure vs gc_hardware_update for capture settings. Descriptions do explicitly distinguish these (SIGSTOP vs TAS-friendly pause, atomic press_once vs press/release), which keeps misselection limited.
Strong, predictable gc_<domain>_<verb_noun> pattern throughout (gc_instance_start, gc_controller_press_once, gc_memory_read_struct, gc_hardware_register). Minor deviations exist for noun-only tools (gc_log, gc_server_info, gc_gpu_info, gc_controller_get_state), but all names are snake_case with the gc_ prefix and are readable.
45 tools is well above the 25-tool threshold and heavy even for a broad emulator+hardware surface; several could be consolidated (press/release/press_once/flick, set_stick, set_trigger; platform_list vs instance_list; hardware_update vs capture_configure). The scope is genuinely multi-domain, but the surface is larger than necessary for coherent selection.
Coverage is broad and lifecycle-complete in most areas: instance and hardware CRUD, full controller input including sequences, memory read/write (raw and struct), save-states, hotkeys, config, capture, and logs. Notable gaps are explicitly stated — controller driving over serial for real hardware is not implemented, and hardware button-press to return to Swiss is missing — but these are minor relative to the overall surface.