Skip to content

Command line and MCP ​

The studio's project code is also a command line and an MCP server, so an agent (Claude Code or any MCP client) can work on a game without overwriting hand-made art, music and levels.

sh
gba-studio validate <folder> [--json]            # every problem; exit 1 on errors
gba-studio build <folder> [--release] [--json]   # run the project's build command
gba-studio schema                                # JSON Schema of every document kind
gba-studio agents <folder> [--claude]            # write AGENTS.md; --claude also sets up Claude Code
gba-studio mcp <folder>                          # MCP server over stdio

From a checkout, gba-studio is node <this repo>/server/src/cli.ts.

Setting up Claude Code ​

sh
gba-studio agents ../my-game --claude

writes three things into the game folder, leaving anything already there alone unless you add --force:

  • AGENTS.md: which files are hand-made and must not be regenerated, how the format works, and which tools to use. (Also written whenever a project is created.)
  • .claude/skills/gba-studio/SKILL.md: a skill that tells Claude when to use the tools and in what order: look, change, check, show, run.
  • .mcp.json: the studio's server, added beside any other servers in the file.

Two ways to connect ​

Stdio: gba-studio mcp <folder>The running studio: http://127.0.0.1:4517/mcp
Needs the studio openNoYes
Sees what you have on screen (studio_view)NoYes
Can show you an item (studio_open)NoYes
Builds appear in the Build panelNoYes
What it did shows in the studio's top barNoYes

Either way, the edits are file saves: an open studio shows them at once, and Ctrl+Z in the studio undoes an agent's change. To use the studio's endpoint from Claude Code:

json
{ "mcpServers": { "gba-studio": { "type": "http", "url": "http://127.0.0.1:4517/mcp" } } }

The endpoint refuses requests from other web pages, like the rest of the server.

The tools ​

ToolsWhat they do
project_overview, validate, list_assetsSummarise the project, list its problems, list asset files
read_document, write_document, delete_documentWhole documents, checked against the schemas before writing
room_read_cells, room_fill, room_paintRead and change tile layers and collision by cell, without touching the run-length data
room_create, room_resize, room_update, world_placeMake, size and rename rooms, set their tileset, music and backgrounds, arrange the world map
entity_add, entity_update, entity_removeEntities in a room
entity_type_set, entity_type_removeEntity types and their typed properties
tileset_create, tileset_set_collisionTilesets from a PNG in the folder; collision classes by tile list or range
sprite_create, sprite_set_animation, sprite_remove_animation, sprite_set_geometrySprites from a sheet in the folder, their animations, anchor and hitbox
audio_addAdd a WAV, XM, MOD or MIDI file in the folder as a sound effect or track
render_room, render_tileset, render_spritePictures: a room (optionally tinted by collision), a tileset or sprite sheet with its grid
build, run_romBuild the ROM; run it headless for given frames and held buttons and get a picture after each step
studio_view, studio_openWhat the author has open; put an item in front of them (studio endpoint only)

Every write is validated and answered with the problems it left in that file. Errors inside a tool come back as text the agent can act on ("the tileset has 16 tiles, numbered 0 to 15; there is no tile 99").

Art and music are yours

No tool creates, changes or deletes a file under assets/: agents can use the art and music that is there, not make it.

Screenshots show the Diamond Hands project open in the studio.