A Model Context Protocol (MCP) server for serverboy, allowing LLMs to interact with a GameBoy emulator. Yo 8000 ur LLM can...
- Load ROMS
- Press Keys
- Look at the Gameboy Screen
- skip frames
You can...
- control the gameboy emulator using the @modelcontextprotocol/inspector
- control the gameboy emulator (and upload ROMs) using a web-interface at http://localhost:3001/emulator
- install the gameboy emulator in your favorite MCP-Client
- Supports both stdio and SSE transports
- Provides tools for GameBoy controls (up, down, left, right, A, B, start, select)
- Provides tools to load different ROMs
- Provides tools to get the current screen
- All tools return an ImageContent with the latest screen frame
To install GameBoy Emulator Server for Claude Desktop automatically via Smithery:
npx -y @smithery/cli install @mario-andreschak/mcp-gameboy --client claudeInstalling in FLUJO
- Click Add Server
- Copy & Paste Github URL into FLUJO
- Click Parse, Clone, Install, Build and Save.
# Clone the repository
git clone https://github.com/yourusername/mcp-gameboy.git
cd mcp-gameboy
# Install dependencies
npm install
# Build the project
npm run build!! ATTENTION : Many MCP Clients require to specify the ROM-Path in the .env vars as an absolute path
To integrate this MCP server with Cline or other MCP clients via configuration files:
-
Open your Cline settings:
- In VS Code, go to File -> Preferences -> Settings
- Search for "Cline MCP Settings"
- Click "Edit in settings.json"
-
Add the server configuration to the
mcpServersobject:{ "mcpServers": { "mcp-gameboy": { "command": "node", "args": [ "/path/to/mcp-gameboy/dist/index.js" ], "disabled": false, "autoApprove": [] } } } -
Replace
/path/to/mcp-gameboy/dist/index.jswith the actual path to theindex.jsfile in your project directory. Use forward slashes (/) or double backslashes (\\) for the path on Windows. -
Save the settings file. Cline should automatically connect to the server.
!! ATTENTION : Many MCP Clients require to specify the ROM-Path in the .env vars as an absolute path
Create a .env file in the root directory with the following variables:
# Server configuration
PORT=3001
# ROM path for stdio mode
ROM_PATH=./roms/dangan.gb
In stdio mode, the server uses the ROM path specified in the ROM_PATH environment variable. It will open a browser window to display the GameBoy screen.
npm run startIn SSE mode, the server starts an Express server that serves a web page for ROM selection.
npm run start-sseThen open your browser to http://localhost:3001 to select a ROM.
The server provides the following tools:
press_up: Press the UP button on the GameBoypress_down: Press the DOWN button on the GameBoypress_left: Press the LEFT button on the GameBoypress_right: Press the RIGHT button on the GameBoypress_a: Press the A button on the GameBoypress_b: Press the B button on the GameBoypress_start: Press the START button on the GameBoypress_select: Press the SELECT button on the GameBoyload_rom: Load a GameBoy ROM fileget_screen: Get the current GameBoy screen
All tools return an ImageContent with the latest screen frame.
This server is built using the Model Context Protocol (MCP) TypeScript SDK. It uses:
McpServerfrom@modelcontextprotocol/sdk/server/mcp.jsfor the server implementationStdioServerTransportfrom@modelcontextprotocol/sdk/server/stdio.jsfor stdio transportSSEServerTransportfrom@modelcontextprotocol/sdk/server/sse.jsfor SSE transportserverboyfor the GameBoy emulationexpressfor the web server in SSE modecanvasfor rendering the GameBoy screen
MIT