MCP GameBoy Server

# MCP GameBoy Server [](https://smithery.ai/server/@mario-andreschak/mcp-gameboy) <a href="https://glama.ai/mcp/servers/@mario-andreschak/mcp-gameboy"> <img width="380" height="200" src="https://glama.ai/mcp/servers/@mario-andreschak/mcp-gameboy/badge" alt="GameBoy Server MCP server" /> </a> ## 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](https://smithery.ai/server/@mario-andreschak/mcp-gameboy): ```bash npx -y @smithery/cli install @mario-andreschak/mcp-gameboy --client claude ``` ### Installing in [FLUJO](https://github.com/mario-andreschak/FLUJO/) 1. Click Add Server 2. Copy & Paste Github URL into FLUJO 3. Click Parse, Clone, Install, Build and Save. ### Manual Installation ```bash # 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: ```json { "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. ```bash npm run start ``` ### Running in SSE Mode In SSE mode, the server starts an Express server that serves a web page for ROM selection. ```bash 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