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:

• Project Design
• Technical Architecture
• MVP Implementation Roadmap

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