MCP PyBoy Emulator Server

An MCP (Model Context Protocol) server that enables LLMs to interact with Game Boy games through PyBoy emulation.

Overview

This server provides LLMs with the ability to:

🎮 Load and play Game Boy ROM files
🎯 Control games through button inputs and sequences
📸 Capture and analyze game screens
💾 Save and load game states
📝 Maintain persistent knowledge about games

Prerequisites

Python 3.10 or higher
uv - Fast Python package manager
A compatible LLM client that supports MCP protocol

Installation

1. Install uv (if not already installed)

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

# Or using pip
pip install uv

2. Clone the repository

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

3. Set up the development environment

# Install all dependencies (creates .venv automatically)
uv sync

# Install with development dependencies
uv sync --extra dev

4. Verify installation

# Check the CLI works
uv run mcp-pyboy

# Run tests (when implemented)
uv run pytest

Quick Start

Running the Server

# Basic usage
uv run mcp-pyboy

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

Project Structure

mcp-pyboy/
├── src/mcp_pyboy/          # Main package
│   ├── mcp_server/         # MCP protocol implementation
│   ├── game_session/       # PyBoy emulator wrapper
│   ├── notebook/           # Knowledge persistence
│   ├── handlers/           # MCP tool implementations
│   └── utils/              # Shared utilities
├── tests/                  # Test suite
├── docs/                   # Architecture documentation
├── roms/                   # ROM files directory
├── saves/                  # Save states directory
└── notebooks/              # Game knowledge storage

Development

Development Tools

This project uses modern Python development tools:

uv - Fast dependency management
Black - Code formatting (88 char line length)
Ruff - Linting and import sorting
MyPy - Static type checking
pytest - Testing framework

Common Development 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

# Install new dependency
uv add <package-name>

# Install dev dependency
uv add --dev <package-name>

VS Code Integration

This project includes VS Code configuration for optimal development:

.vscode/settings.json - Workspace settings with Black/Ruff integration
.vscode/extensions.json - Recommended extensions

The configuration ensures:

Black handles all formatting
Ruff handles linting only (no formatting conflicts)
Proper Python interpreter from virtual environment

MCP Tools Available

Once fully implemented, the server will provide these tools:

Emulation Control

load_rom - Load a Game Boy ROM file
reset_game - Reset the current game
set_emulation_speed - Control game speed

Input Control

press_button - Press a Game Boy button
hold_button - Hold a button down
release_button - Release a held button
send_input_sequence - Execute a sequence of inputs

Screen and State

capture_screen - Get current game screen
save_state - Save current game state
load_state - Load a saved state
list_states - List available save states

Knowledge Management

create_note - Create a note about the game
update_note - Update existing note
search_notes - Search game knowledge
list_notes - List all notes for current game

Architecture

For detailed architecture documentation, see:

Contributing

This project is under active development. See the MVP Roadmap for current progress and planned features.

License

[License information to be added]

Acknowledgments

Built on PyBoy - Game Boy emulator
Uses MCP - Model Context Protocol
Developed with Claude Code assistance

This server cannot be installed

security - not tested

license - permissive license

quality - not tested

How are these scores calculated?

A Model Context Protocol server that allows LLMs to interact with Game Boy games through PyBoy emulation, providing capabilities to load ROMs, control games, capture screens, save/load states, and maintain game knowledge.

Related MCP Servers

MCP Python Interpreter
yzfly
A
security
F
license
A
quality
A Model Context Protocol server that allows LLMs to interact with Python environments, execute code, and manage files within a specified working directory.
Last updated -
9
42
Python
MCP Python SDK
imax09-wq
-
security
-
license
-
quality
A Python implementation of the Model Context Protocol that allows applications to provide standardized context for LLMs, enabling creation of servers that expose data and functionality to LLM applications through resources, tools, and prompts.
Last updated -
Python
MIT License
PokeAPI MCP Server
AkhrHysd
-
security
-
license
-
quality
A Model Context Protocol server that interfaces with PokeAPI to provide Pokémon information to LLM applications through JSON-RPC over stdio.
Last updated -
TypeScript
MCP GameBoy Server
mario-andreschak
A
security
A
license
A
quality
A Model Context Protocol server that enables LLMs to interact with a GameBoy emulator, providing tools for controlling the GameBoy, loading ROMs, and retrieving screen frames.
Last updated -
13
5
TypeScript
MIT License

View all related MCP servers

MCP PyBoy Emulator Server