MCP PyBoy

You can run an MCP server that lets an LLM interact with Game Boy games through PyBoy emulation. It enables loading ROMs, sending button inputs, capturing screens, saving and loading game states, and keeping game knowledge persistently available for smarter interactions.

How to use

You connect your MCP client to the PyBoy Emulator Server to drive gameplay and extract information. Load a ROM, press buttons or run input sequences to control the game, capture the current screen for analysis, and save or restore progress. You can also create and update notes about each game so the LLM can reason with contextual knowledge over time.

Typical usage patterns include loading a ROM once per session, starting from a known state, stepping through gameplay with precise input sequences, capturing screens for vision analysis, and saving states after key moments. Use knowledge notes to accumulate game-specific tips, strategies, and observed behaviors for faster decision making in future interactions.

How to install

Prerequisites you need before installing the server.

Install uv (Python package manager) if you don’t have it.

# macOS/Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# Or using pip
pip install uv

Clone the MCP PyBoy repository and navigate into the project directory.

git clone https://github.com/ssimonitch/mcp-pyboy.git
cd mcp-pyboy

Install project dependencies and set up the development environment.

# Install all dependencies (creates a virtual environment if supported by uv)
uv sync

# Install with development dependencies
uv sync --extra dev

Verify the installation by running the server and tests.

# Check the CLI works
uv run mcp-pyboy

# Run tests (when implemented)
uv run pytest

Start the server with basic usage and optional flags for ROMs and log level.

# Basic usage
uv run mcp-pyboy

# With options (coming soon)
uv run mcp-pyboy --roms-dir ./roms --log-level DEBUG

Configuration and runtime

The server is designed to be launched locally via the command line. Use the default start command to begin a session and then interact with the MCP client to drive gameplay.

Development notes

Development tools and practices used include automatic formatting with Black, linting with Ruff, static typing with MyPy, and tests with pytest. You can format, lint, type-check, and run tests using the following commands.

# Format code
uv run black src/ tests/

# Run linter
uv run ruff check src/ tests/

# Type check
uv run mypy src/

# Run tests
uv run pytest tests/ -v

Available tools

load_rom

Load a Game Boy ROM file into the active session so you can start or resume gameplay.

reset_game

Reset the current game to its initial state or a known starting point.

set_emulation_speed

Control the speed of the emulation to balance performance and accuracy.

press_button

Simulate pressing a single Game Boy button for one frame or a specified duration.

hold_button

Hold a specific button down to perform long actions or combos.

release_button

Release a previously held button to resume normal gameplay.

send_input_sequence

Execute a sequence of button inputs to perform timed actions or complex maneuvers.

capture_screen

Capture the current game screen as an image for analysis or display.

save_state

Save the current emulation state to allow exact restoration later.

load_state

Load a previously saved emulation state to continue from that point.

list_states

List all available saved states for quick selection.

create_note

Create a note describing observations or strategies for a specific game.

update_note

Update an existing knowledge note with new information.

search_notes

Search the knowledge base for notes related to the current game.

list_notes

List all notes stored for the current game.