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

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

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

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

# Or using pip
pip install uv

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

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

# Install with development dependencies
uv sync --extra dev

# Check the CLI works
uv run mcp-pyboy

# Run tests (when implemented)
uv run pytest

# Basic usage
uv run mcp-pyboy

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

mcp-pyboy/
├── src/mcp_server/          # 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

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

# 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>

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

Once fully implemented, the server will provide these tools:

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

• 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

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

• 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

For detailed architecture documentation, see:

• Project Design
• Technical Architecture
• MVP Implementation Roadmap

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

[License information to be added]

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