Skip to main content
Glama

Server Configuration

Describes the environment variables required to run the server.

NameRequiredDescriptionDefault
GC_MCP_BBA_MODENoBBA mode: ipc, hle, xlink, tap, tapserver, or empty/none.ipc
GC_MCP_DATA_DIRNoRoot for per-instance data and captures.~/.gc-mcp
GC_MCP_GPU_ACCELNoGPU acceleration mode: auto, none, software, vgl, vgl-egl, or vgl-glx.auto
GC_MCP_HW_BBA_IPNoDefault BBA IP for a new hardware instance; the console's own IP, used to reach the Swiss netboot listener.
GC_MCP_GPU_DEVICENoGPU DRM device path, e.g. /dev/dri/card2.auto-detected
GC_MCP_NATIVE_RESNoGameCube native framebuffer size as WxH, used for display/capture sizing.640x480
GC_MCP_HW_BBA_PORTNoDefault Swiss netboot listener port.4242
GC_MCP_VIDEO_BACKENDNoVideo backend: OGL, Vulkan, or Software Renderer.OGL
GC_MCP_BBA_MAC_PREFIXNoMust be 00:09:bf or 00:17:ab.00:09:bf
GC_MCP_DOLPHIN_BINARYNoDolphin executable.dolphin-emu
GC_MCP_HW_CAPTURE_FPSNoDefault hardware capture frame rate.30
GC_MCP_MEMORY_BACKENDNoMemory backend: process_vm or dolphin_engine.process_vm
GC_MCP_VGL_3D_DISPLAYNo3D X server display for VirtualGL's GLX back end, e.g. :0.0.
GC_MCP_CAPTURE_BACKENDNoCapture backend: auto, xvfb, or framedump.auto
GC_MCP_HW_CAPTURE_FLUSHNoNumber of stale buffers flushed before reading a fresh frame on the OpenCV path.5
GC_MCP_HW_CAPTURE_WIDTHNoDefault hardware capture width.640
GC_MCP_HW_CAPTURE_DEVICENoDefault capture device for real hardware instances./dev/video0
GC_MCP_HW_CAPTURE_FORMATNoDefault hardware capture pixel format, e.g. mjpg or yuyv.mjpg
GC_MCP_HW_CAPTURE_HEIGHTNoDefault hardware capture height.480
GC_MCP_HW_CAPTURE_WARMUPNoSeconds to stream a cold device before grabbing a frame; 0 disables.5
GC_MCP_HW_CAPTURE_WARMUP_TTLNoSeconds 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

CapabilityDetails
tools
{
  "listChanged": false
}
prompts
{
  "listChanged": false
}
resources
{
  "subscribe": false,
  "listChanged": false
}

Tools

Functions exposed to the LLM to take actions

NameDescription
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 /dev/shm SIGBUS crash that occurs when the shared-memory filesystem is too small for Dolphin's emulated RAM.

gc_platform_listA

List the platforms currently available to control.

Includes each running Dolphin instance (dolphin:<id>) and each registered real GameCube hardware instance (gamecube-hw:<id>).

gc_platform_capabilitiesB

Describe the capabilities of a platform.

platform may be dolphin:<instance_id> or gamecube-hw:<id>.

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. /dev/video0) as its capture_device so the server can grab frames from the console. Each entry reports the node, its card name, the pixel formats it offers, and whether it can actually capture video frames (can_capture). Some nodes expose only UVC metadata and cannot produce a video stream, so prefer one with can_capture: true.

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 gc_hardware_remove.

Args: instance_id: Unique id for the hardware instance (e.g. hw-001). capture_device: Video4Linux2 device path (default /dev/video0). Prefer a device reported with can_capture: true by gc_hardware_devices. capture: Optional capture options, e.g. {"width": 640, "height": 480, "format": "mjpg", "fps": 30, "flush_frames": 5, "warmup_seconds": 5, "warmup_ttl": 60}. warmup_seconds is how long a cold capture card is streamed before grabbing a frame (0 disables). serial_devices: Up to four serial device paths that will act as the GameCube controller ports (0-3). Controller driving is not yet implemented, but the devices are remembered. bba_ip: The console's own BBA IP (e.g. 192.0.2.10), used by gc_rom_load to reach the Swiss netboot listener. bba_port: The netboot listener port (default 4242). info: Free-form description/annotation shown in list and status output.

gc_hardware_updateB

Update a registered hardware instance's settings and persist them.

Use this to set the console's bba_ip (its own IP) so gc_rom_load can reach the Swiss netboot listener, or to change the capture device / ports / info annotation.

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_hardware_register to re-add it.

gc_logA

Read this instance's Dolphin log file (<user_dir>/dolphin.log).

Useful for diagnosing crashes, OSReport output from the ROM, or emulator warnings. grep keeps only lines containing the (case-insensitive) substring. tail returns only the last tail lines of the (possibly filtered) output. Returns the matching lines and some metadata.

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. opts may include a capture dict of capture options.

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:

  • Real GameCube hardware — sends a BOOT command to the console's Swiss netboot listener (TCP 4242 on the instance's bba_ip). rom_path must be a console-side path (sdc:/ or fsp:/, e.g. sdc:/games/Foo.iso). If the console is currently inside a game the listener is down; this first tries to return to Swiss with the A+Z+START combo (which needs hardware button pressing, not implemented yet).

    Raises :class:NetbootError if the BOOT command is not answered with OK — including when the listener returns no reply at all (console mid-boot / dropped connection) or refuses the ROM (ERR <reason>).

  • Dolphin instance — stops the current process and relaunches it booting the given host-side ROM/DOL/ELF path.

For hardware, set the console's IP with gc_hardware_update(instance_id, bba_ip='<console-ip>') before loading a ROM.

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 address and unpack it with a Python struct format.

fmt is a Python :mod:struct format string, e.g. ">12f" for twelve big-endian floats (a 3x4 transform matrix), ">II" for two big-endian u32 values, or ">4h" for four big-endian s16 values.

GameCube is big-endian, so include a byte-order prefix in fmt: > (big-endian, standard sizes) or ! (network order). If you omit it the format uses the host's native byte order/sizes, which is almost never what you want for a GameCube, so it is recommended to always prefix with >.

The result values is a list of the unpacked values in format order.

gc_memory_write_structB

Pack values with a Python struct format and write them to memory.

fmt is a Python :mod:struct format string (see gc_memory_read_struct for the byte-order notes). values is a list of the values to pack, in format order, e.g. for ">12f" pass 12 floats.

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, gc_dolphin_step_frame advances exactly one frame.

This injects a keystroke into the instance's X display via xdotool, so it requires the xvfb capture backend and xdotool installed. On a headless --batch instance Dolphin's [Input] BackgroundInput = True keeps the input gate open so the hotkey is received without window focus.

gc_dolphin_step_frameA

Advance exactly one frame when the emulator is paused.

Sends Dolphin's Frame Advance hotkey. Unlike Step Into (a CPU-debugger step), Frame Advance steps one video frame, which is what a TAS tool wants.

The instance config binds Frame Advance to F8 by default (see gc_dolphin_hotkey_get/gc_dolphin_hotkey_set). If it is unbound this tool returns ok=False and no frame advances.

gc_dolphin_save_stateA

Save a save-state to slot (1-8) via Shift+F{slot}, then copy it.

Only slots 1-8 have a Dolphin default hotkey binding (see gc_dolphin_hotkey_get).

After saving, the state file is copied into copy_dir (or the server's configured states directory, <data>/states, by default). The result includes copied, state_file and copied_to.

gc_dolphin_load_stateB

Load a save-state from slot (1-8) via F{slot}.

Only slots 1-8 have a Dolphin default hotkey binding (see gc_dolphin_hotkey_get).

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_toggle_pause for a TAS-friendly pause.

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.

key is the Hotkeys.ini key <group>/<control> (e.g. General/Toggle Pause, Save State/Save State Slot 1). Returns the current binding expression (F10, @(Shift+F1)), or None if the hotkey is unbound. This is Dolphin-only (real hardware has no emulator hotkeys).

gc_dolphin_hotkey_setA

Set (or clear) a Dolphin emulator hotkey binding.

key is the Hotkeys.ini key <group>/<control>. expression is the binding in Dolphin input syntax, e.g. F8 for a single key or @(Shift+F8) for a combination. Pass expression="" to unbind it.

Dolphin loads Hotkeys.ini all-or-nothing, so this preserves every existing binding and the built-in default set, then applies key. A running instance may need a restart for the change to take effect. This is Dolphin-only.

Common keys (see gc_dolphin_* tools): General/Toggle Pause, Frame Advance/Frame Advance, Save State/Save State Slot 1..8, Load State/Load State Slot 1..8.

Prompts

Interactive templates invoked by user choice

NameDescription

No prompts

Resources

Contextual data attached and managed by the client

NameDescription

No resources

TDQS

B3.2/5.0

Scored across 45 tools

Disambiguation4/5

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.

Naming Consistency4/5

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.

Tool Count2/5

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.

Completeness4/5

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.

Maintenance

ActivityMaintained
ResponsivenessNo recent community issues