GB Studio MCP Server

io.github.eoinjordan由 GitHub 帳號 eoinjordan 發布v1.0.4更新於 Oct 24, 2026

Create and modify GB Studio projects with MCP tools for scenes, actors, assets, and validation.

發布方自己的服務:Claude Platform Docs

已驗證STDIO僅桌面開發者工具媒體與設計

概覽

AI 產生的概覽

讓助理建立與修改 GB Studio / GBA Studio 遊戲專案(場景、角色、素材、設定)、驗證專案,並建置 GBA ROM。

可以做什麼
  • 尋找並驗證 GB Studio 專案,列出其中的場景、角色、觸發器與素材
  • 在專案中建立場景、角色與觸發器
  • 建立素材:精靈、背景、圖塊集、調色盤、字型、音樂、音效、表情、頭像、腳本、變數、常數與預製件
  • 更新專案設定與中繼資料
  • 從本機 GBA Studio 程式碼庫建置 .gba ROM
適用情境
適合讓助理在 GB Studio 中搭建或擴充 Game Boy / Game Boy Color / GBA 遊戲專案,用於教學、原型製作或反覆調整可玩範本,並在同一段對話中完成驗證或 ROM 建置。
執行需求
需透過 npm 在本機安裝(Node.js,建議 v21.7.1 或相容版本),並使用 Claude Desktop 等桌面 MCP 用戶端。stdio 伺服器會代理到 localhost:3000 的本機 REST API,因此須先啟動該服務;連接埠可用 GBSTUDIO_API_URL 或 GBSTUDIO_API_PORT 變更。建置 ROM 需要本機 GBA Studio 程式碼庫(GBA_STUDIO_ROOT)。CLAUDE_API_KEY 為選用。
安裝前請注意
伺服器會寫入專案檔案:建立與更新端點會新增場景、角色、素材並修改設定與中繼資料,建議在副本或版本控制下操作。選用的 CLAUDE_API_KEY 會從環境變數或 .env 檔讀取,也可透過端點設定,請勿提交到原始碼庫。REST API 監聽本機並接受專案路徑,只應在可信任的機器上執行。

安裝

在 SourceWeft 中

  1. 開啟 儀表板中的 GB Studio MCP Server,將其新增到工作區。
  2. 為需要使用其工具的對話啟用該服務。

Desktop only,透過 STDIO。 STDIO 服務會啟動本機處理程序,因此需要 SourceWeft 桌面主機。

其他 MCP 客戶端

參照 儲存庫 中的啟動說明。

README

GB Studio / GBA Studio Agentic MCP Server for creating GameBoy Games.

Prompt to build out a template for your students, kids, or yourself to extend.

[image]

[Image]

[GIF]

Also works for GBA STUDIO ...my fork of GB Studio that covers the GBA

Quick Start

  1. Install: npm install -g gbstudio-claude-mcp

  2. Start server: gbstudio-claude-mcp

  3. Connect Claude Desktop (see TUTORIAL.md)

  4. Prompt Claude: "Review and test my application logic"

That’s it. Claude will reivew, extend or even generate a playable game template you can iterate on with students in GB Studio.

Vibe Coding, LLMs, and Modern Education: Can give students Constructive Tools, Not Just Answers

After 14 years teaching kids programming, electronics, 3D printing, and game development, I’ve learned this: the best educational tools don’t just make things easier. They make learning a rewarding activity. GB Studio is one of those tools. It’s a visual game builder that gives you a Game Boy development, putting real creative power in the hands of students, educators, and hobbyists to build for physical hardware. When we combine GB Studio with education on what is possible to do with large language models (LLMs), we bring a postitive view to students on how they can integrate with rather than rely on them as a crutch.

What is Vibe Coding?

“Vibe coding” isn’t just a buzzword. It’s a paradigm shift. It’s programming stripped of syntactic gatekeeping, where creators focus on flow, logic, and ideas instead of memorizing semicolons. Tools like Scratch, App Inventor, and GB Studio embody this philosophy: they eliminate barriers and recenter programming around what actually matters: creativity and problem-solving.

For kids, vibe coding is a what they are growing up with. It will let them focus on the “why” and “how” of programming without drowning in syntax. This isn’t just helpful. It’s important for students to get to think in systems, design, and logic but are shut out by traditional coding’s steep learning curve.

The Role of LLMs in Education

Large language models like ChatGPT have sparked fierce debate in education, and for good reason. Used carelessly, they become cheating tools that replaces thinking with copy-pasa mindset. But used with purpos, they can become scaffolding that accelerates real learning. The difference isn’t the tool. It’s how we wield it.

This is exactly why I built the Clawdbot MCP server. By integrating LLMs directly with GB Studio, users and teachers can:

  • Scaffold projects: Generate starter templates, assets, and event flows from simple prompts.
  • Automate testing: Run smoke tests to catch bugs and validate project logic.
  • Encourage iteration: Help students refine their projects by providing suggestions and examples.

Games can be built from scratch too but they wont be AAA class so measure your expectations lol

Pong (Game Boy)

Create a Pong clone for the original Game Boy. Two paddles, a ball, and a score counter. The player controls the left paddle, the right paddle is AI-controlled. Use simple monochrome graphics and authentic GB sound effects. Generate all scenes, actors, and assets for a playable Pong game.

Pac-Man (Game Boy Color)

Build a Pac-Man style maze game for Game Boy Color. The player navigates a maze, collects pellets, and avoids ghosts. Include at least one maze layout, four ghosts with basic AI, and colorful graphics. Generate all scenes, actors, and assets needed for a playable demo.

Mario Bros Style Platformer (Game Boy Color)

Design a Mario Bros inspired platformer for Game Boy Color. The player can run, jump, and stomp on enemies. Include three levels, power-ups, coins, and a flagpole at the end of each level. Use bright palettes and catchy background music. Generate all scenes, actors, and assets for a classic platformer experience.

Space Shooter (Game Boy)

Create a vertical scrolling space shooter for the original Game Boy. The player controls a spaceship, shoots enemies, and dodges obstacles. Include multiple enemy types, power-ups, and a boss fight. Use classic GB graphics and chiptune sound effects. Generate all scenes, actors, and assets for a playable shooter.

Claude MCP Server for GB Studio

This is a TypeScript server for manipulating GB Studio projects using the Model Context Protocol (MCP). It provides endpoints for project discovery, validation, and creation of game assets.


Installation

Install globally with npm:

sh
npm install -g gbstudio-claude-mcp

Local Environment Setup (.env)

For local development, store API keys and configuration in a .env file at the project root. This keeps secrets out of source control and matches the pattern used in GitHub Actions.

  1. Create a .env file in the project root:
    env
    CLAUDE_API_KEY=your-claude-api-key-here# Add other keys as needed
  2. The server will automatically load variables from .env if you use [dotenv].
  3. .env files are gitignored by default.

Never commit your .env file to source control.


Usage

Start the server:

sh
gbstudio-claude-mcp

The server runs on http://localhost:3000 by default.

Configure your MCP client (e.g., Claude Desktop) to connect to this server. For full setup and troubleshooting, see the tutorial linked at the end of this document.


End-to-End Usage: Windows & Linux/macOS

See the TUTORIAL.md for a complete, step-by-step guide to building a GB Studio game with this server, including screenshots and troubleshooting tips for both Windows and Linux/macOS.


MCP Protocol Support

This package supports the Model Context Protocol (MCP). You can run the server in MCP stdio mode for use with Claude Desktop and other MCP clients:

sh
npm run build:mcpnode build/mcp.js

The MCP stdio server proxies to the local REST API on http://localhost:3000, so start the REST server first. To use a different port, set GBSTUDIO_API_URL (full URL) or GBSTUDIO_API_PORT (port number):

sh
gbstudio-claude-mcp

Or add this to your MCP client configuration:

{   "mcpServers": {      "gbstudio-mcp": {         "command": "node",         "args": ["/absolute/path/to/build/mcp.js"]      }   }}

Clawdbot / Moltbot Compatibility

[Screenshot_20260128-214729 WhatsApp]

Clawdbot and Moltbot discover tools via AgentSkills-compatible SKILL.md files. This repo ships one at:

  • skills/gbstudio-mcp/SKILL.md

Compatibility depends on transport:

  • If Clawdbot can run stdio MCP servers as child processes, node build/mcp.js will work.
  • If your Clawdbot setup expects HTTP+SSE MCP servers, you will need a bridge, because this MCP server is stdio-only.
  • If you only run the REST API, Clawdbot will not auto-discover tools as MCP.

To enable the skill in Moltbot, add an entry like this:

json
{  "skills": {    "load": {      "extraDirs": [        "~/.clawdbot/skills"      ],      "watch": true,      "watchDebounceMs": 250    },    "entries": {      "gbstudio-mcp": {        "enabled": true,        "env": {}      }    }  }}

Project Structure

  • src/index.ts — Main server and endpoint logic
  • tests/ — Jest test suites for all endpoints
  • tests/poachermon/ — Real GB Studio project for integration tests
  • gbstudio_api_endpoints.csv — Catalog of all planned endpoints

Local Development

  1. Clone the repository:
    sh
    git clone https://github.com/eoinjordan/gb-studio-agent.gitcd gb-studio-agent
  2. Install Node.js (recommended: v21.7.1 or compatible)
  3. Install dependencies:
    sh
    npm install
  4. Start the development server:
    sh
    npm run dev
  5. Run the test suite:
    sh
    npm test

Health

  • GET /health — Returns { status: "ok" } for health checks.

Claude API Key

  • GET /claude-key — Returns { present: true } if CLAUDE_API_KEY is set in the environment, else { present: false } with 404.

Find Project

  • POST /find_project — Finds the first .gbsproj file starting from a given directory.
    • Body: { startPath: string }
    • Returns: { projectPath: string } or 404 if not found.

Inventory

  • POST /inventory — Lists scenes, actors, triggers, and assets from a GB Studio project root.
    • Body: { projectRoot: string }
    • Returns: { scenes, actors, triggers, assets } or 404/400 on error.

Validate

  • POST /validate — Validates the structure of a GB Studio project (checks for a valid .gbsproj file and required fields).
    • Body: { projectRoot: string }
    • Returns: { valid: true, message: string, scenes: number, projectPath: string, target: "gb" | "gba", engine: "gb-studio" | "gba-studio", version: string | null } if valid, or 400/404 with an error message if invalid or missing required fields.
    • Error Cases:
      • 400 if projectRoot is missing or .gbsproj is invalid/missing required fields
      • 404 if projectRoot does not exist or no .gbsproj file found

Build GBA ROM

  • POST /gba/build — Builds a .gba ROM using a local GBA Studio checkout.
    • Body: { projectRoot: string, gbaStudioRoot?: string, output?: string, buildCli?: boolean, verbose?: boolean, extraArgs?: string[] }
    • Environment: GBA_STUDIO_ROOT can be used instead of gbaStudioRoot.
    • Returns: { success: true, projectPath, gbaStudioRoot, output, stdout, stderr } on success, or { success: false, error, stdout, stderr }.
    • MCP tool: build_gba_rom exposes the same arguments for Claude/agent clients.

Create Scene

  • POST /scene/create — Adds a new scene to the specified GB Studio project.
    • Body: { projectRoot: string, scene: object }
    • Returns: { success: true, scene } on success, or 400/404/500 with an error message.

Create Actor

  • POST /actor/create — Creates a new actor in the specified scene.
    • Body: { projectRoot: string, sceneId: string, actor: object }
    • Returns: { success: true, actor } on success, or 400/404/500 with an error message.

Create Background

  • POST /background/create — Creates a new background in the project.
    • Body: { projectRoot: string, background: object }
    • Returns: { success: true, background } on success, or 400/404/500 with an error message.

Create Sprite

  • POST /sprite/create — Creates a new sprite in the project.
    • Body: { projectRoot: string, sprite: object }
    • Returns: { success: true, sprite } on success, or 400/404/500 with an error message.

Create Music

  • POST /music/create — Creates a new music track in the project.
    • Body: { projectRoot: string, music: object }
    • Returns: { success: true, music } on success, or 400/404/500 with an error message.

Create Sound

  • POST /sound/create — Creates a new sound effect in the project.
    • Body: { projectRoot: string, sound: object }
    • Returns: { success: true, sound } on success, or 400/404/500 with an error message.

Create Tileset

  • POST /tileset/create — Creates a new tileset in the project.
    • Body: { projectRoot: string, tileset: object }
    • Returns: { success: true, tileset } on success, or 400/404/500 with an error message.

Create Trigger

  • POST /trigger/create — Creates a new trigger in the specified scene.
    • Body: { projectRoot: string, sceneId: string, trigger: object }
    • Returns: { success: true, trigger } on success, or 400/404/500 with an error message.

Create Variable

  • POST /variable/create — Creates a new variable in the project.
    • Body: { projectRoot: string, variable: object }
    • Returns: { success: true, variable } on success, or 400/404/500 with an error message.

Create Script

  • POST /script/create — Creates a new script in the project.
    • Body: { projectRoot: string, script: object }
    • Returns: { success: true, script } on success, or 400/404/500 with an error message.

Create Palette

  • POST /palette/create — Creates a new palette in the project.
    • Body: { projectRoot: string, palette: object }
    • Returns: { success: true, palette } on success, or 400/404/500 with an error message.

Create Font

  • POST /font/create — Creates a new font in the project.
    • Body: { projectRoot: string, font: object }
    • Returns: { success: true, font } on success, or 400/404/500 with an error message.

Create Emote

  • POST /emote/create — Creates a new emote in the project.
    • Body: { projectRoot: string, emote: object }
    • Returns: { success: true, emote } on success, or 400/404/500 with an error message.

Create Avatar

  • POST /avatar/create — Creates a new avatar in the project.
    • Body: { projectRoot: string, avatar: object }
    • Returns: { success: true, avatar } on success, or 400/404/500 with an error message.

Create Constant

  • POST /constant/create — Creates a new constant in the project.
    • Body: { projectRoot: string, constant: object }
    • Returns: { success: true, constant } on success, or 400/404/500 with an error message.

Create Prefab Actor

  • POST /prefab/actor/create — Creates a new actor prefab in the project.
    • Body: { projectRoot: string, actorPrefab: object }
    • Returns: { success: true, actorPrefab } on success, or 400/404/500 with an error message.

Create Prefab Trigger

  • POST /prefab/trigger/create — Creates a new trigger prefab in the project.
    • Body: { projectRoot: string, triggerPrefab: object }
    • Returns: { success: true, triggerPrefab } on success, or 400/404/500 with an error message.

Update Settings

  • POST /settings/update — Updates project settings.
    • Body: { projectRoot: string, settings: object }
    • Returns: { success: true, settings } on success, or 400/404/500 with an error message.

Update Metadata

  • POST /metadata/update — Updates project metadata.
    • Body: { projectRoot: string, metadata: object }
    • Returns: { success: true, metadata } on success, or 400/404/500 with an error message.

Create Engine Field Value

  • POST /engine-field-value/create — Creates a new engine field value in the project.
    • Body: { projectRoot: string, engineFieldValue: object }
    • Returns: { success: true, engineFieldValue } on success, or 400/404/500 with an error message.

Claude Key

  • POST /claude/key — Sets the Claude API key in the environment.
    • Body: { key: string }
    • Returns: { success: true } on success, or 400 with an error message.

Building a Game End-to-End

To build a GB Studio game using this MCP server with Claude:

  1. Discover Project: Use /find_project to locate an existing .gbsproj file or start from a directory.
  2. Validate Project: Use /validate to ensure the project is valid.
  3. Get Inventory: Use /inventory to list current scenes, actors, triggers, assets.
  4. Create Scenes: Use /scene/create to add new scenes.
  5. Create Actors: Use /actor/create to add actors to scenes.
  6. Create Assets: Use creation endpoints (currently stubs) to add sprites, backgrounds, etc.
  7. Update Settings/Metadata: Use update endpoints to configure the project.
  8. Build/Export: Use /gba/build or MCP build_gba_rom to compile a GBA Studio project to .gba.

Note: All endpoints are now fully functional.

GBA Studio Build Example

json
{  "projectRoot": "C:/Users/Eoin/git/gba-studio/examples/gba-starter-project",  "gbaStudioRoot": "C:/Users/Eoin/git/gba-studio",  "output": "C:/tmp/gba-starter.gba",  "buildCli": true}

Example Prompts

See TUTORIAL.md for detailed sample prompts and full end-to-end workflows for different game genres.

Test Coverage

All endpoints are covered by Jest tests in the tests/ directory. Run npm test to validate all functionality. Tests use real sample projects.

Publishing

To publish a new version:

  1. Update version in package.json
  2. Build the project:
    sh
    npm run build
  3. Login to npm:
    sh
    npm login --auth-type=legacy
  4. Publish to npm:
    sh
    npm publish --access public

See npm publishing docs for more info.

Contributing

  1. Fork the repository
  2. Create a feature branch
  3. Make changes and add tests
  4. Submit a pull request to https://github.com/eoinjordan/gb-studio-agent

License

MIT

來源:README.md,提交 ee97909

工具

0
SourceWeft 尚未在沙箱中啟動過該軟體包,因此其工具未知。

版本歷史

1
  1. v1.0.4最新Sep 16, 2026

評分

已滿足適用檢查項的 40%

該評分衡量此收錄條目的完整程度,依據註冊中心條目、端點與公開來源計算得出。它不是對伺服器本身的評價,也不表示伺服器安全或目前可用:可連通性是帶日期的檢查結果,評分也不包含安裝量或使用者評價。

  • 近 30 天內可連通25 分

    請保持端點能夠回應 MCP 握手;SourceWeft 每 30 天探測一次。

  • 已宣告認證方式10 分

    請在註冊中心條目中宣告憑證請求標頭,或保持端點能夠回應探測,以便判定其認證方式。

  • 已列出工具15 分

    請讓伺服器在無憑證時回應 tools/list,或發布可在沙箱中無憑證啟動的軟體包。

  • 描述必需15 分
  • 圖示10 分
  • 文件15 分
  • 授權條款10 分

    請在儲存庫或註冊中心條目中宣告授權條款。

其他 Claude 整合