@gbs-toolkit/mcp-server

MCP server for structured GB Studio 4.x project editing — read/patch scripts, scenes, actors, triggers, variables; build ROMs; sprite generation pipeline.

Designed to be driven by an LLM coding assistant (Claude Code, Cursor, etc.) so the model can mutate .gbsres resources safely instead of dropping bytes into JSON by hand.

Install

npm install -g @gbs-toolkit/mcp-server

Or invoke on demand via npx:

npx -y @gbs-toolkit/mcp-server

Run as an MCP server

The server speaks stdio MCP. Most users wire it up in their LLM client's .mcp.json:

{
  "mcpServers": {
    "gbs": {
      "command": "npx",
      "args": ["-y", "@gbs-toolkit/mcp-server"],
      "env": {
        "GBS_PROJECT_ROOT": "./gbsproj/demo"
      }
    }
  }
}

Environment variables

Variable	Required	Default	Notes
GBS_PROJECT_ROOT	yes	—	Directory containing <name>.gbsproj
GBS_CLI_PATH	no	probes common install locations	Absolute path to gb-studio-cli.js
GBS_MGBA_RUNNER	no	none	Path to a libmgba-linked runner binary used by run_emulator (build it from native/build.sh)
GBS_ROM_OUT	no	<root>/build	Output directory for build_rom
GBS_LOG_PATH	no	<root>/build/compile.log	Captured compile log
GBS_SCREENSHOT_DIR	no	<root>/build/screenshots	Where run_emulator drops PNGs
SPRITE_PROVIDER	no	openai	openai / gemini / replicate / fal
OPENAI_API_KEY	conditional	—	Required if SPRITE_PROVIDER=openai and generate_sprite is used
GEMINI_API_KEY	conditional	—	Required for gemini provider
REPLICATE_API_TOKEN	conditional	—	Required for replicate provider
FAL_KEY	conditional	—	Required for fal provider

Tool inventory

Tool	Kind
list_scenes / read_scene / list_actors / read_script / read_compile_log	read
patch_script	write (insert / replace / delete, applied in order)
set_variable	write (upserts a VARIABLE_SET_TO_VALUE event in the start scene's onInit)
create_scene / create_actor / create_trigger / create_variable / create_custom_event / set_start_scene	write
delete_scene / delete_actor / delete_trigger / delete_custom_event / delete_variable	write (cross-script reference scan; refuses unless force: true)
generate_sprite	write (text-to-image → 4-colour DMG quantise → emits (asset.png, asset.png.gbsres))
convert_image_to_sprite	write (no AI; same pipeline applied to a user-supplied PNG/JPG)
build_rom	subprocess (spawns GB Studio CLI's make:rom)
run_emulator	subprocess (drives a libmgba-linked C runner)
screenshot	read image (returns base64 PNG as multimodal MCP content)

What is NOT exposed

Creation/import of binary assets stays GUI-side: backgrounds, tilesets, emotes, avatars, fonts, music, sounds, plus actorPrefabs / triggerPrefabs / palettes / notes. The MCP layer can read and patch scripts that reference these resources by id, but cannot create their .png / .uge / .wav payloads. Sprites are the one exception (see generate_sprite / convert_image_to_sprite).

Built-in guardrails

The server enforces two checks that previously had to live in prompts:

1. Dialogue width audit — patch_script validates every EVENT_TEXT / EVENT_MENU / EVENT_CHOICE / EVENT_DIALOGUE / EVENT_MARQUEE string against the GB Studio default-font line budget (18 columns; $var$ placeholders reserve 5 chars to cover signed-16-bit values). Multi-box text: string[] form, CJK width (2 columns / char), and recursive children branches are all walked. A violation rejects the patch with DIALOGUE_WIDTH_EXCEEDED and a per-line breakdown. Pass widthBudget to override (e.g. for a custom narrow font) or force: true to bypass.

2. Sprite quality check — generate_sprite and convert_image_to_sprite analyse the post-quantisation RGBA buffer (opaque ratio, effective DMG colour count, edge density, single-shade dominance). Clearly degenerate outputs (near-empty frame, ≤1 effective shade) refuse to write the asset; borderline cases (2 shades, low edge density, >85% one shade) save with a quality.level: "warn" field in the response. Pass force: true to skip the check.

Both checks return structured metadata so the LLM can self-correct rather than ploughing through.

Building the emulator runner

run_emulator requires a libmgba-linked C binary. Stock mGBA CLIs do not accept a startup --script flag, so we ship a small dedicated runner. From the cloned repo:

cd native
MGBA_SRC=/path/to/mgba MGBA_BUILD=/path/to/mgba/build ./build.sh

Then point the env var at the result: GBS_MGBA_RUNNER=/path/to/gbs-mgba-runner.

If you don't need run_emulator, ignore this — every other tool works without it.

License

MIT