GameBoy Emulator MCP server

This MCP GameBoy Server allows LLMs to interact with a GameBoy emulator, enabling them to load ROMs, press keys, view the GameBoy screen, and skip frames. It provides a bridge between language models and interactive GameBoy gameplay through the Model Context Protocol.

Installation Options

Via Smithery

The easiest way to install the GameBoy Emulator Server for Claude Desktop is through Smithery:

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

Via FLUJO

To install in FLUJO:

1. Click Add Server
2. Copy & Paste the 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

Via Configuration Files

To integrate with Cline or other MCP clients via configuration files:

1. Open your Cline settings in VS Code (File → Preferences → Settings)
2. Search for "Cline MCP Settings" and click "Edit in settings.json"
3. Add the server configuration:

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

Important: 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 Windows paths.

Usage

Environment Setup

Create a .env file in the root directory:

# Server configuration
PORT=3001

# ROM path for stdio mode
ROM_PATH=./roms/dangan.gb

Important: Many MCP clients require specifying the ROM_PATH as an absolute path in the environment variables.

Running in stdio Mode

This mode uses the ROM path from your environment variables and opens a browser window showing the GameBoy screen:

npm run start

Running in SSE Mode

This mode starts an Express server with a web interface for ROM selection:

npm run start-sse

After starting, open your browser to http://localhost:3001 to select a ROM. You can also access the emulator interface at http://localhost:3001/emulator.

Available Tools

The server provides these tools for GameBoy interaction:

• Button Controls:

  • press_up: Press the UP button
  • press_down: Press the DOWN button
  • press_left: Press the LEFT button
  • press_right: Press the RIGHT button
  • press_a: Press the A button
  • press_b: Press the B button
  • press_start: Press the START button
  • press_select: Press the SELECT button

• ROM and Display:

  • load_rom: Load a GameBoy ROM file
  • get_screen: Get the current GameBoy screen

All tools return an ImageContent with the latest screen frame, allowing the LLM to see the current state of the game.

Web Interface

You can control the GameBoy emulator and upload ROMs using these interfaces:

• Web interface at http://localhost:3001/emulator
• MCP Inspector tool using @modelcontextprotocol/inspector

How to add this MCP server to Cursor

There are two ways to add an MCP server to Cursor. The most common way is to add the server globally in the ~/.cursor/mcp.json file so that it is available in all of your projects.

If you only need the server in a single project, you can add it to the project instead by creating or adding it to the .cursor/mcp.json file.

Adding an MCP server to Cursor globally

To add a global MCP server go to Cursor Settings > MCP and click "Add new global MCP server".

When you click that button the ~/.cursor/mcp.json file will be opened and you can add your server like this:

{
    "mcpServers": {
        "cursor-rules-mcp": {
            "command": "npx",
            "args": [
                "-y",
                "cursor-rules-mcp"
            ]
        }
    }
}

Adding an MCP server to a project

To add an MCP server to a project you can create a new .cursor/mcp.json file or add it to the existing one. This will look exactly the same as the global MCP server example above.

How to use the MCP server

Once the server is installed, you might need to head back to Settings > MCP and click the refresh button.

The Cursor agent will then be able to see the available tools the added MCP server has available and will call them when it needs to.

You can also explictly ask the agent to use the tool by mentioning the tool name and describing what the function does.