mcp-gameboy

MCP GameBoy Server

Overview

A Model Context Protocol (MCP) server for serverboy, allowing LLMs to interact with a GameBoy emulator. Your 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

Features

• 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

Installation

Installing via Smithery

To install GameBoy Emulator Server for Claude Desktop automatically via Smithery:

npx -y @smithery/cli install @mario-andreschak/mcp-gameboy --client claude

Installing in FLUJO

1. Click Add Server
2. Copy & Paste Github URL into FLUJO
3. Click Parse, Clone, Install, Build and Save.

Manual Installation

# 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

Installing via Configuration Files

!! 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:

1. Open your Cline settings:

   • In VS Code, go to File -> Preferences -> Settings
   • Search for "Cline MCP Settings"
   • Click "Edit in settings.json"

2. Add the server configuration to the mcpServers object:

   {
     "mcpServers": {
       "mcp-gameboy": {
         "command": "node",
         "args": [
           "/path/to/mcp-gameboy/dist/index.js"
         ],
         "disabled": false,
         "autoApprove": []
       }
     }
   }
   

3. Replace /path/to/mcp-gameboy/dist/index.js with the actual path to the index.js file in your project directory. Use forward slashes (/) or double backslashes (\\) for the path on Windows.

4. Save the settings file. Cline should automatically connect to the server.

Usage

Environment Variables

!! 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

Running in stdio Mode

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 start

Running in SSE Mode

In SSE mode, the server starts an Express server that serves a web page for ROM selection.

npm run start-sse

Then open your browser to http://localhost:3001 to select a ROM.

Tools

The server provides the following tools:

• press_up: Press the UP button on the GameBoy
• press_down: Press the DOWN button on the GameBoy
• press_left: Press the LEFT button on the GameBoy
• press_right: Press the RIGHT button on the GameBoy
• press_a: Press the A button on the GameBoy
• press_b: Press the B button on the GameBoy
• press_start: Press the START button on the GameBoy
• press_select: Press the SELECT button on the GameBoy
• load_rom: Load a GameBoy ROM file
• get_screen: Get the current GameBoy screen

All tools return an ImageContent with the latest screen frame.

Implementation Details

This server is built using the Model Context Protocol (MCP) TypeScript SDK. It uses:

• McpServer from @modelcontextprotocol/sdk/server/mcp.js for the server implementation
• StdioServerTransport from @modelcontextprotocol/sdk/server/stdio.js for stdio transport
• SSEServerTransport from @modelcontextprotocol/sdk/server/sse.js for SSE transport
• serverboy for the GameBoy emulation
• express for the web server in SSE mode
• canvas for rendering the GameBoy screen

License

MIT