GB Studio Claude

This MCP server connects GB Studio projects with Claude’s capabilities to scaffold, test, and extend game templates. It enables you to start from a playable GB Studio base, prompt Claude to review and enhance your project, and iterate with students or yourself to build interactive Game Boy experiences.

How to use

You use this server with an MCP client to manage GB Studio projects through Claude. Start by launching the server, then connect your MCP client (such as Claude Desktop) to it. You can instruct Claude to review, extend, or generate a playable game template, and the server will apply those changes to your GB Studio project.

How to install

Prerequisites: ensure you have Node.js installed on your machine.

Install the MCP server globally with npm.

npm install -g gbstudio-claude-mcp

Start the MCP server.

gbstudio-claude-mcp

If you are using a Claude client, configure the client to connect to the local MCP server and follow the TUTORIAL guidance to set up the connection.

Configuration and usage notes

Local development can leverage a .env file to supply API keys and configuration. A typical setup includes a Claude API key stored in CLAUDE_API_KEY.

The server serves the REST API at the local endpoint and can be extended via MCP to manage GB Studio project assets.

End-to-end workflow with Claude in GB Studio

1. Discover or create a GB Studio project and locate its .gbsproj file.

2. Use the MCP endpoints to inventory scenes, actors, and assets, and validate the project structure.

3. Create new scenes, actors, backgrounds, tilesets, and other assets as needed.

4. Prompt Claude to review or generate template assets and event flows, then iterate on the results to build a playable game.

Examples prompts (conceptual)

Prompts can request starter templates or feature enhancements. For example, you could ask Claude to generate a Pong clone, a Pac-Man style maze, or a Mario Bros inspired platformer, tailored for GB Studio.

Security and data handling

Keep sensitive keys in environment files and do not commit them to source control. The server loads configuration from a local environment source and should be connected only to trusted clients in secure environments.

Available tools

Discover Project

Searches for the first .gbsproj file starting from a given path to identify the GB Studio project root.

Validate Project

Checks that the project has a valid .gbsproj file and required fields, returning a validation result and any issues.

Inventory

Lists scenes, actors, triggers, and assets from the GB Studio project root so you can understand current content.

Create Scene

Adds a new scene to the GB Studio project with provided scene data.

Create Actor

Creates a new actor within a specified scene.

Create Background

Adds a new background to the project.

Create Sprite

Adds a new sprite to the project.

Create Music

Adds a new music track to the project.

Create Sound

Adds a new sound effect to the project.

Create Tileset

Adds a new tileset to the project.

Create Trigger

Creates a new trigger within a specified scene.

Create Variable

Creates a new variable in the project.

Create Script

Creates a new script within the project.

Create Palette

Creates a new palette in the project.

Create Font

Creates a new font in the project.

Create Emote

Creates a new emote in the project.

Create Avatar

Creates a new avatar in the project.

Create Constant

Creates a new constant in the project.

Create Prefab Actor

Creates a new actor prefab in the project.

Create Prefab Trigger

Creates a new trigger prefab in the project.

Update Settings

Updates project settings.

Update Metadata

Updates project metadata.

Create Engine Field Value

Creates a new engine field value in the project.

Claude Key

Sets the Claude API key in the environment.