retroMCP

nbhansen/retroMCP

3.3

If you are the rightful owner of retroMCP and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to henry@mcphub.com.

RetroMCP is an MCP server that connects AI assistants to RetroPie systems for configuration and troubleshooting.

Tools

  1. manage_system

    System operations including connection test, info, packages, and updates.

  2. manage_gaming

    Gaming operations such as RetroPie setup, EmulationStation management, and controller configuration.

  3. manage_hardware

    Hardware operations including temperature monitoring, fan checks, and power health.

  4. manage_docker

    Docker operations for container, image, and service management.

  5. manage_state

    Load, save, update, and compare system state.

RetroMCP

An MCP server that connects AI assistants to Raspberry Pi systems for comprehensive system administration and RetroPie management.

RetroMCP enables AI assistants like Claude to help configure and manage Raspberry Pi systems through SSH connections. From gaming setup to system administration - ask questions in natural language instead of learning Linux commands.

Claude Talking to Your RetroPie Setup

Claude analyzing your Raspberry Pi 5 hardware specifications and system information

Claude discovering and managing your GameCube ROM collection

Claude detecting PS5 controllers and providing configuration guidance

How It Works

Natural language requests are translated through Claude Desktop via MCP protocol to SSH commands executed on your Raspberry Pi.

Examples:

  • "Set up my Xbox controller" - Installs drivers and configures button mappings
  • "My N64 games are slow" - Checks performance and suggests tuning options
  • "Find missing BIOS files" - Identifies required files for your emulators
  • "Monitor CPU temperature" - Tracks system health and cooling performance

Problem Solved

Raspberry Pi and RetroPie administration typically requires Linux command line expertise, manual configuration file editing, and hardware-specific knowledge. RetroMCP eliminates this by providing AI assistants with secure SSH connectivity, automatic system discovery, and comprehensive context about your specific setup.

Key Features

  • Dynamic System Discovery - Automatic detection of usernames, paths, and configurations
  • State Management - Persistent system tracking with backup/restore capabilities
  • Performance Optimization - TTL-based caching for expensive operations
  • AI Context Sharing - System state exposed via MCP Resources for effective troubleshooting

Project Status

Current Phase: v2.0 production implementation
Security Status: Comprehensive security validation
Test Coverage: 89% overall coverage with comprehensive testing infrastructure

Installation

1. Enable SSH on RetroPie

On your Raspberry Pi:

  1. Press F4 to exit EmulationStation
  2. Run: sudo raspi-config
  3. Go to "Interface Options" → "SSH" → Enable
  4. Note your Pi's IP address: hostname -I

2. Configure Passwordless Sudo (Required)

WARNING: This allows any user with SSH access to run any command as root without a password. Only do this on dedicated gaming systems.

RetroMCP requires passwordless sudo for package installation, service management, and system configuration. On your RetroPie system:

# Edit sudoers file
sudo visudo

# Add this line at the end (replace 'pi' with your username):
pi ALL=(ALL) NOPASSWD:ALL

# Or for the retro user:
retro ALL=(ALL) NOPASSWD:ALL

# Save and exit (Ctrl+X, then Y, then Enter in nano)

3. Install RetroMCP

# Clone repository
git clone <repository-url>
cd retroMCP

# Create virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install dependencies
pip install -e .

4. Configure Connection

# Copy example configuration
cp .env.example .env

# Edit with your Pi's details
nano .env

Required settings in .env:

RETROPIE_HOST=192.168.1.100  # Your Pi's IP address
RETROPIE_USERNAME=retro       # SSH username (auto-detected after first connection)
RETROPIE_PASSWORD=password    # SSH password
# OR
RETROPIE_SSH_KEY_PATH=~/.ssh/id_rsa  # Path to SSH key

Claude Desktop Integration

Configuration

Config file location:

  • Mac: ~/Library/Application Support/Claude/claude_desktop_config.json
  • Windows: %APPDATA%\Claude\claude_desktop_config.json
  • Linux: ~/.config/Claude/claude_desktop_config.json

Configuration:

{
  "mcpServers": {
    "retromcp": {
      "command": "python",
      "args": ["-m", "retromcp.server"],
      "cwd": "/absolute/path/to/retroMCP"
    }
  }
}

Restart Claude Desktop to load the server.

Available Tools

System Management

  • manage_system - Connection testing, system info, package management, updates

Gaming System

  • manage_gaming - RetroPie configuration, EmulationStation, controllers, ROMs, emulators, audio/video

Hardware Monitoring

  • manage_hardware - Temperature monitoring, fan control, power status, GPIO operations

Docker Management

  • manage_docker - Container and image management, service operations

State Management

  • manage_state - System state persistence, backup/restore, configuration drift detection

Security Features

  • SSH Security - Host key verification, connection timeouts, credential cleanup
  • Input Protection - Command injection prevention, parameter validation, path traversal blocking
  • Error Handling - Information sanitization and secure error recovery

Testing

Test Strategy

RetroMCP uses comprehensive test-driven development with 89% code coverage:

  • Unit Tests: Domain logic and tool functionality testing
  • Integration Tests: End-to-end SSH and MCP protocol validation
  • Contract Tests: Architecture compliance and hexagonal pattern verification
  • Infrastructure Tests: SSH repositories and external service mocking

Running Tests

# Run all tests
make test

# Component-specific testing
make test-hardware    # Hardware monitoring tools
make test-gaming      # Gaming system tools  
make test-state       # State management tools
make test-ssh         # SSH infrastructure

# Using smart test runner
python run_tests.py --hardware --coverage
python run_tests.py --quick --gaming

# Convenience scripts
./test_hardware.sh
./test_gaming.sh

MCP Inspector

# Test MCP protocol compliance
./scripts/test-inspector.sh
npx @modelcontextprotocol/inspector python -m retromcp.server

Troubleshooting

Connection Issues

  • Verify SSH is enabled on the Pi
  • Check firewall settings
  • Ensure credentials in .env are correct
  • Test SSH manually: ssh pi@<your-pi-ip>

Permission Issues

  • RetroMCP requires passwordless sudo for system operations
  • Ensure your user has NOPASSWD:ALL configured in sudoers
  • Check RetroPie directory ownership if file operations fail

MCP Inspector Issues

  • Ensure Node.js is installed: node --version
  • Update npm if needed: npm install -g npm
  • Clear npm cache: npm cache clean --force

Security Issues

  • Verify known_hosts file exists: ~/.ssh/known_hosts
  • Check SSH key permissions: chmod 600 ~/.ssh/id_rsa
  • Review error messages for security warnings

Background

  • RetroPie - Retro gaming platform for Raspberry Pi
  • MCP - Protocol enabling AI assistants to interact with external systems

Documentation

  • - Complete technical architecture documentation
  • - AI assistant development guidelines

License

MIT