VICE MCP - AI Meets the Commodore 64

_VICE MCP is a Walker Heavy Industries project._

An MCP server embedded directly inside VICE, giving AI agents and modern tools

full programmatic control over the world's most iconic 8-bit computer.

> Load a disk image. Set breakpoints. Inspect sprites. Read SID registers.

> Type on the keyboard. Take screenshots. Step through 6502 code.

> All through a clean JSON-RPC API that any MCP client can speak.

This is VICE — the legendary Commodore emulator —

with a Model Context Protocol server built into its core.

Not bolted on. Not a wrapper. ~17,000 lines of C woven into the emulator itself.

What Can You Do With This?

For AI Agents

Point any MCP-compatible client - Claude Desktop, Cursor, your own agent - at

`http://127.0.0.1:6510/mcp` and you have a fully controllable Commodore 64.

Your agent can:

• Load and run software — autostart PRGs and disk images
• Debug 6502 code — breakpoints, watchpoints, conditional breaks, single-stepping
• Inspect everything — CPU registers, memory banks, VIC-II graphics, SID audio, CIA timers
• See what's on screen — take screenshots, read sprite bitmaps as ASCII art
• Interact like a human — type text, press keys, move joysticks
• Measure performance — cycle-accurate stopwatch, execution tracing, interrupt logging
• Save and restore state — full snapshot management with metadata

For C64 Developers

If you write code for the Commodore 64, this gives you a modern debugging workflow

without leaving your editor:

• Set breakpoints from your IDE while your program runs
• Load KickAssembler or VICE symbol files and debug by label name
• Search memory for byte patterns with wildcard support
• Compare memory regions against saved snapshots to find what changed
• Trace execution with PC-range filtering to focus on your code
• Log interrupts to understand IRQ/NMI timing
• Group breakpoints and toggle them as a set

For Researchers & Educators

• Automate ROM analysis and reverse engineering
• Build interactive tutorials that control a live C64
• Capture screen states for documentation
• Replay and analyze historical software

63 Tools Across 14 Categories

Every tool follows MCP conventions with full JSON Schema validation, meaningful errors,

and consistent parameter naming.

Architecture

This isn't a sidecar process or a screen-scraper. The MCP server is compiled directly

into VICE as a first-class subsystem — across every machine VICE emulates.

Supported Machines

The MCP server adapts to the running machine automatically. When an AI agent

calls `vice.machine.config.get`, it receives the actual hardware configuration — which

chips are present, what memory banks exist, valid address ranges, and available

resources. An agent debugging a VIC-20 cartridge gets VIC-I registers; the same

agent debugging a C128 program gets VIC-II *and* the VDC 80-column display.

┌─────────────────────────────────────────────────┐
│                   VICE Emulator                  │
│                                                  │
│  ┌──────────┐  ┌──────────┐  ┌──────────────┐  │
│  │   CPU    │  │  Video   │  │    Audio     │  │
│  │ (varies) │  │ (varies) │  │   (varies)   │  │
│  └────┬─────┘  └────┬─────┘  └──────┬───────┘  │
│       │              │               │           │
│       └──────────┬───┴───────────────┘           │
│                  │                                │
│         ┌────────┴────────┐                      │
│         │  MCP Server     │                      │
│         │  (libmcp.a)     │                      │
│         │                 │                      │
│         │  JSON-RPC 2.0   ││
│         │  Trap Dispatch  │                      │
│         └─────────────────┘                      │
│                                                  │
└─────────────────────────────────────────────────┘
        127.0.0.1:6510 by default

Key design decisions:

• Trap-based dispatch — HTTP requests are dispatched through VICE's trap mechanism,

ensuring all tool logic executes on the emulator's main thread. No race conditions,

no locking surprises.

• Zero-copy access — Tools read directly from emulator internals. When you ask for

VIC-II state, you get the actual register values, not a cached approximation.

• Machine-aware responses — Tools report hardware capabilities, chip availability,

and valid memory ranges for whatever machine is running. The agent always knows

what it's working with.

• Monitor integration — Works alongside VICE's built-in monitor. If the emulator

is paused in the monitor, MCP requests execute directly without traps.

• Reserved events endpoint — `GET /events` exists but currently returns

`501 Not Implemented`. Poll state through `/mcp` until event streaming lands.

Quick Start

Connect to VICE

Start any VICE machine with the MCP server enabled:

# C64 (cycle-exact)
x64sc -mcpserver

# C128
x128 -mcpserver

# VIC-20
xvic -mcpserver

# Listen on all network interfaces, port 7000
x64sc -mcpserver -mcpserverhost 0.0.0.0 -mcpserverport 7000

The MCP server starts on `127.0.0.1:6510` by default. MCP clients connect to:

http://127.0.0.1:6510/mcp

`0.0.0.0` is a bind address, not a client address. It means "listen on every

interface". A client on the same Mac still connects to `127.0.0.1`; a client on

another machine connects to the Mac's LAN IP address, for example

`http://192.168.1.42:6510/mcp`.

Connection Recipes

Token rules are intentionally simple:

• No token configured: non-browser MCP clients can connect without an

`Authorization` header.

• Token configured: every MCP request must include

`Authorization: Bearer `.

• CORS configured: a token is required. Wildcard CORS (`*`) is rejected.
• Binding to `0.0.0.0` without a token is allowed for backwards compatibility,

but VICE logs a warning because remote clients can control the emulator.

Talk to It

All HTTP requests go to `/mcp`, must use `Content-Type: application/json`, and

should send `Accept: application/json`.

# Direct JSON-RPC call
curl -sS http://127.0.0.1:6510/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  --data '{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "vice.ping"
}'

# Standard MCP tools/call form, used by Claude Code and other MCP clients
curl -sS http://127.0.0.1:6510/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  --data '{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": { "name": "vice_ping", "arguments": {} }
}'

# Read the BASIC ROM entry point
curl -sS http://127.0.0.1:6510/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  --data '{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "vice_memory_read",
    "arguments": { "address": "0xA000", "size": 16, "encoding": "hex" }
  }
}'

When a token is configured, add the bearer header to every request:

curl -sS http://127.0.0.1:6510/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer secret' \
  --data '{"jsonrpc":"2.0","id":1,"method":"vice.ping"}'

Use with Claude Desktop

Add this to your Claude Desktop MCP config:

{
  "mcpServers": {
    "vice": {
      "url": "http://127.0.0.1:6510/mcp"
    }
  }
}

Then just talk to it: *"Load the game on drive 8 and show me what's on screen."*

If VICE was started with `-mcpservertoken`, the client must send

`Authorization: Bearer ` on every request. If your MCP client cannot

configure HTTP headers, do not use a token for local-only `127.0.0.1` sessions.

Building from Source

Prerequisites

Build

cd vice
./autogen.sh
mkdir build && cd build
../configure --enable-mcp-server --enable-gtk3ui
make -j$(nproc)

Verify

# MCP flags should appear in help output
src/x64sc -help | grep mcp

# Expected:
# -mcpserver          Enable MCP server
# -mcpserverport   Set MCP server port (default: 6510)
# -mcpserverhost   Set MCP server host (default: 127.0.0.1)

Pre-built Binaries

Pre-built binaries are available on the Releases page.

Windows does not include a GUI build. GTK3 cross-compilation for Windows is not

supported by VICE's build system. If you need a Windows GUI, build from source

natively using MSYS2.

Python Client

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)

Protocol Test Suite

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

Real-World Usage

sim6502 — Unit Testing for 6502 Assembly

sim6502 is a unit testing framework for

6502/6510/65C02 assembly that uses VICE MCP as an execution backend. Write tests

in a custom DSL, run them against a live VICE instance with cycle-accurate hardware:

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.

AI Agent Workflows

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

Security

The MCP server is localhost-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 to `0.0.0.0` is supported via `-mcpserverhost`. That makes VICE listen

on every network interface. It does not mean clients connect to `0.0.0.0`; remote

clients connect to the Mac/Linux/Windows host's real IP address.

Use this checklist for remote sessions:

• Start VICE with `-mcpserverhost 0.0.0.0`.
• Prefer adding `-mcpservertoken ` unless the network is already trusted.
• Configure the client URL as `http://:6510/mcp`.
• If a token is configured, configure the client to send

`Authorization: Bearer `.

• For browser-based clients, also configure one exact

`-mcpservercorsorigin ` and a token. CORS without a token is rejected.

Relationship to Upstream VICE

This is a fork of the VICE SVN mirror.

The MCP server is implemented as a self-contained subsystem in `src/mcp/` — it

touches VICE internals through well-defined interfaces but doesn't modify core

emulation logic.

The `main` branch tracks upstream VICE. The `mcp-server` branch 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.

Tool Reference

Click to expand full reference for all 64 tools

Execution Control

`vice.ping`

Check if VICE is responding. No parameters.

`vice.execution.run`

Resume execution. No parameters.

`vice.execution.pause`

Pause execution. No parameters.

`vice.execution.step`

Step one or more instructions.

`vice.run_until`

Run until address or for N cycles with timeout.

Registers

`vice.registers.get`

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

`vice.registers.set`

Set a CPU register value.

Memory

`vice.memory.read`

Read a memory range with optional bank selection.

`vice.memory.write`

Write bytes to memory.

`vice.memory.banks`

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

`vice.memory.search`

Search for byte patterns with optional wildcard mask.

`vice.memory.fill`

Fill a memory range with a repeating byte pattern.

`vice.memory.compare`

Compare two memory ranges or compare against a snapshot.

Checkpoints & Breakpoints

`vice.checkpoint.add`

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

`vice.checkpoint.delete`

Delete a checkpoint.

`vice.checkpoint.list`

List all checkpoints. No parameters.

`vice.checkpoint.toggle`

Enable or disable a checkpoint.

`vice.checkpoint.set_condition`

Set a condition expression on a checkpoint.

`vice.checkpoint.set_ignore_count`

Set how many hits to ignore before stopping.

`vice.checkpoint.group.create`

Create a named checkpoint group.

`vice.checkpoint.group.add`

Add checkpoints to an existing group.

`vice.checkpoint.group.toggle`

Enable or disable all checkpoints in a group.

`vice.checkpoint.group.list`

List all checkpoint groups. No parameters.

`vice.checkpoint.set_auto_snapshot`

Auto-save a snapshot when a checkpoint is hit.

`vice.checkpoint.clear_auto_snapshot`

Remove auto-snapshot from a checkpoint.

Sprites (C64/C128/DTV)

`vice.sprite.get`

Get sprite state.

`vice.sprite.set`

Set sprite properties.

`vice.sprite.inspect`

Visual ASCII art representation of a sprite's bitmap.

Chip State

`vice.vicii.get_state`

Get VIC-II internal state. No parameters.

`vice.vicii.set_state`

Set VIC-II registers.

`vice.sid.get_state`

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

`vice.sid.set_state`

Set SID registers.

`vice.cia.get_state`

Get CIA state (timers, ports).

`vice.cia.set_state`

Set CIA registers.

Disk Management

`vice.disk.attach`

Attach a disk image to a drive.

`vice.disk.detach`

Detach a disk image.

`vice.disk.list`

List directory contents of an attached disk.

`vice.disk.read_sector`

Read raw sector data.

Machine Control

`vice.autostart`

Autostart a PRG or disk image.

`vice.machine.reset`

Reset the machine.

`vice.machine.config.get`

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

`vice.machine.config.set`

Set machine resources.

Display

`vice.display.screenshot`

Capture the screen.

`vice.display.get_dimensions`

Get display dimensions. No parameters.

Input

`vice.keyboard.type`

Type text with automatic PETSCII conversion.

`vice.keyboard.key_press`

Press a key.

`vice.keyboard.key_release`

Release a key.

`vice.keyboard.restore`

Press/release the RESTORE key (triggers NMI).

`vice.keyboard.matrix`

Direct keyboard matrix control for games.

`vice.joystick.set`

Set joystick state.

Advanced Debugging

`vice.disassemble`

Disassemble memory to 6502 instructions.

`vice.symbols.load`

Load a symbol/label file.

`vice.symbols.lookup`

Look up a symbol by name or address.

`vice.watch.add`

Add a memory watchpoint.

`vice.backtrace`

Show call stack from JSR return addresses.

`vice.cycles.stopwatch`

Measure elapsed CPU cycles.

Snapshots

`vice.snapshot.save`

Save complete emulator state.

`vice.snapshot.load`

Restore emulator state from a snapshot.

`vice.snapshot.list`

List all snapshots with metadata. No parameters.

Execution Tracing

`vice.trace.start`

Start recording executed instructions.

`vice.trace.stop`

Stop tracing and get statistics.

Interrupt Logging

`vice.interrupt.log.start`

Start logging IRQ, NMI, and BRK events.

`vice.interrupt.log.stop`

Stop logging and retrieve all entries.

`vice.interrupt.log.read`

Read entries without stopping the log.

Project Status

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.

What's solid:

• 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

What's in progress:

• Event streaming. `GET /events` is reserved but returns `501 Not Implemented` today.
• Execution tracing and interrupt logging hooks into VICE CPU core

Contributing

> *"Cross over, children. All are welcome. All welcome."*

> — Tangina Barrons, speaking to contributors about this repo

This project bridges two communities that don't often overlap: retro computing

and modern AI tooling. Contributions from either world (or both) are welcome.

Areas where help would be especially appreciated:

• VICE internals — Hooking execution tracing and interrupt logging into the CPU core
• Event streaming transport — Adding real-time breakpoint and state-change notifications
• Additional machine support — Testing and tuning tools for PET, CBM-II, Plus/4
• Client libraries — TypeScript, Rust, Go clients
• Documentation — Tutorials, example workflows, video demos
• Testing — Running the protocol test suite against edge cases

The MCP server is entirely contained in `vice/src/mcp/`. Start there.

Versioning & releases

This repo follows the Walker Heavy Industries Build & Release Standard:

• Conventional Commits are required. Versioning is automated with

Cocogitto — `feat:` bumps the minor, `fix:` the

patch, and a `!`/`BREAKING CHANGE` bumps the major. Install the local commit

hook once with `cog install-hook --all` (CI also validates commits).

• On every push to `main`, CI runs `cog bump --auto`, which tags the next

`vX.Y.Z`, updates `CHANGELOG.md`, and publishes a GitHub Release with the

generated changelog notes.

• The multi-OS build matrix (Linux/macOS/Windows) attaches its artifacts to that

Release. The latest `v` tag / Release is the single source of truth for the

version — there is no `compute-version.sh` and no `vice-mcp-*` tag prefix.

License

VICE is released under the GNU General Public License v2. The MCP server additions

follow the same license.

Acknowledgments

• The VICE Team for 30+ years of the best

8-bit emulator ever written

• Anthropic for the Model Context Protocol specification
• The Commodore 64 community — still going strong after four decades

Part of the suite

VICE MCP is part of the Walker Heavy Industries retro toolchain —

modern tools for the retro 8- and 16-bit ecosystem.

• House hub: https://whi.dev
• Siblings: VICE Mac · VICE MCP · FamiForge · NESBasic · Novus · Miggy Draw · NovaVM