VICE MCP

A resilient Python client is included with retry logic, connection pooling, and a convenience method for every tool:

from tools.resilience.vice_mcp_resilient import ViceMCPClient with ViceMCPClient("http://127.0.0.1:6510") as vice: # Load a program vice.autostart("/path/to/game.prg") # Set a breakpoint at the main loop vice.checkpoint_add(start_address=0x0810, stop_address=0x0810) # Run until it hits vice.execution_run() # Read the screen regs = vice.registers_get() screenshot = vice.display_screenshot(format="base64") # Inspect a sprite art = vice.sprite_inspect(sprite_number=0) print(art)

167 tests across 25 test classes validate every tool, every parameter, and every error condition:

# Requires a running VICE instance with MCP enabled pytest tools/tests/test_mcp_protocol.py -v

sim6502 — Unit Testing for 6502 Assembly

suite "sprite collision" { load "game.prg" test "player hits enemy" { jsr setup_sprites poke $d015, #$03 ; enable sprites 0 and 1 poke $d000, #$80 ; sprite 0 x = 128 poke $d002, #$80 ; sprite 1 x = 128 jsr main_loop assert $d01e & #$03 != 0 ; collision register set } }

sim6502 connects over MCP to load programs, set breakpoints, read registers, compare memory, and snapshot/restore state between tests — bringing modern CI/CD practices to retro computing development.

Any MCP-compatible client can drive VICE directly:

- Claude Desktop / Cursor— "Load this disk image, find the main loop, and explain what the IRQ handler does"
- Custom agents— Automated ROM analysis, regression testing, screenshot capture
- Research tools— Systematic exploration of historical software behavior

The MCP server islocalhost-only by default(127.0.0.1). With the default settings, only programs on the same machine can connect.

It has no TLS. It has optional bearer-token authentication. It is designed for local development first, and network exposure should be deliberate.

If you need remote access, put it behind a reverse proxy with proper auth:

nginx/caddy -> auth -> https -> 127.0.0.1:6510

Binding to0.0.0.0is supported via-mcpserverhost. That makes VICE listen on every network interface. It does not mean clients connect to0.0.0.0; remote clients connect to the Mac/Linux/Windows host's real IP address.

- Start VICE with-mcpserverhost 0.0.0.0.
- Prefer adding-mcpservertoken <token>unless the network is already trusted.
- Configure the client URL ashttp://<host-ip>:6510/mcp.
- If a token is configured, configure the client to sendAuthorization: Bearer <token>.
- For browser-based clients, also configure one exact-mcpservercorsorigin <origin>and a token. CORS without a token is rejected.

Themainbranch tracks upstream VICE. Themcp-serverbranch contains all MCP additions.

The goal is to contribute this work back to the VICE project. The implementation is structured to export cleanly as unified diffs for SVN submission.

Check if VICE is responding. No parameters.

Run until address or for N cycles with timeout.

Get all CPU registers (A, X, Y, SP, PC, status flags). No parameters.

Read a memory range with optional bank selection.

List available memory banks for the current machine. No parameters.

Search for byte patterns with optional wildcard mask.

Fill a memory range with a repeating byte pattern.

Compare two memory ranges or compare against a snapshot.

Add a checkpoint (breakpoint, watchpoint, or tracepoint).

Set a condition expression on a checkpoint.

Set how many hits to ignore before stopping.

Enable or disable all checkpoints in a group.

List all checkpoint groups. No parameters.

Auto-save a snapshot when a checkpoint is hit.

Visual ASCII art representation of a sprite's bitmap.

Get VIC-II internal state. No parameters.

Get SID state (voices, filter, ADSR). No parameters.

List directory contents of an attached disk.

Get machine configuration — chips, memory map, resources. No parameters.

Type text with automatic PETSCII conversion.

Press/release the RESTORE key (triggers NMI).

Direct keyboard matrix control for games.

Disassemble memory to 6502 instructions.

Show call stack from JSR return addresses.

List all snapshots with metadata. No parameters.

This is active, working software. The MCP server compiles and runs on Linux, macOS, and Windows. All 64 tools are implemented and tested. CI produces binaries for all three platforms on every push.

- Full tool suite — execution, memory, breakpoints, sprites, chip state, disk, input, debugging
- Machine-aware responses across all VICE-emulated platforms
- Python client with retry logic and full test coverage
- Cross-platform builds: Linux x86_64 (GUI + headless), macOS arm64 (GUI + headless), Windows x86_64 (headless)
- Automated CI/CD pipeline with binary releases

- Event streaming.GET /eventsis reserved but returns501 Not Implementedtoday.
- Execution tracing and interrupt logging hooks into VICE CPU core