VICE C64 Emulator MCP Server

Get current VICE connection and emulation state.

Returns connection status, whether emulation is running or paused, and host/port if connected.

Use this to:

• Check if you're connected before running other commands

• See if emulation is running or stopped (e.g., at a breakpoint)

• Verify connection details

Related tools: connect, disconnect

Connect to a running VICE emulator instance via the binary monitor protocol.

VICE must be started with the binary monitor enabled: x64sc -binarymonitor -binarymonitoraddress ip4://127.0.0.1:6502

Default connection: 127.0.0.1:6502

Use this first before any debugging operations. Connection persists until disconnect() is called or VICE closes.

Related tools: status, disconnect

Disconnect from the VICE emulator instance.

Cleanly closes the connection. Safe to call even if not connected.

Related tools: connect, status

Read memory from the C64's address space.

Returns raw bytes plus hex and ASCII representations.

C64 memory map highlights:

• $0000-$00FF: Zero page (fast access, common variables)

• $0100-$01FF: Stack

• $0400-$07FF: Default screen RAM (1000 bytes)

• $D000-$D3FF: VIC-II registers (graphics)

• $D400-$D7FF: SID registers (sound)

• $D800-$DBFF: Color RAM

For screen content, consider using readScreen instead for interpreted output. For sprite info, use readSprites for semantic data.

Related tools: writeMemory, readScreen, readSprites, readVicState

Write bytes to the C64's memory.

Directly modifies memory at the specified address. Changes take effect immediately.

Common uses:

• Poke values for testing

• Patch code at runtime

• Modify screen/color RAM directly

• Change VIC/SID registers

Be careful writing to ROM areas ($A000-$BFFF, $E000-$FFFF) - you may need to bank out ROM first.

Related tools: readMemory, fillMemory

Get current 6502/6510 CPU register state.

Returns all CPU registers with interpreted flags.

Registers:

• A: Accumulator (arithmetic operations)

• X, Y: Index registers (addressing, loops)

• SP: Stack pointer ($100-$1FF range)

• PC: Program counter (current instruction address)

• Flags: N(egative), V(overflow), B(reak), D(ecimal), I(nterrupt), Z(ero), C(arry)

Use this to:

• Check CPU state at breakpoints

• Understand program flow

• Debug crashes (check PC, SP)

Related tools: setRegister, step, continue, status

Resume C64 execution after a breakpoint or pause.

Starts the emulator running until the next breakpoint, manual stop, or error.

Related tools: step, status, setBreakpoint

Execute one or more instructions, then stop.

Single-stepping is essential for understanding code flow and debugging.

Options:

• count: Number of instructions to execute (default: 1)

• stepOver: If true, treat JSR as single instruction (don't step into subroutines)

After stepping, use getRegisters to see the new CPU state.

Related tools: getRegisters, continue, setBreakpoint, status

Reset the C64 machine.

Options:

• hard: If true, performs hard reset (like power cycle). If false, soft reset (like reset button).

A soft reset preserves some memory contents, hard reset clears everything.

Related tools: connect, status

Set an execution breakpoint at a memory address.

When the PC reaches this address, execution stops. Use to:

• Debug code at specific points

• Catch when routines are called

• Analyze code flow

Returns a breakpoint ID for later management.

Related tools: deleteBreakpoint, listBreakpoints, continue, step

Delete a breakpoint by its ID.

Use listBreakpoints to see current breakpoint IDs.

Related tools: setBreakpoint, listBreakpoints

List all active breakpoints.

Shows breakpoint IDs, addresses, and status for all breakpoints set in this session.

Note: This tracks breakpoints set through this MCP session. Breakpoints set through VICE's built-in monitor may not appear.

Related tools: setBreakpoint, deleteBreakpoint

Enable or disable a breakpoint without deleting it.

Use this to temporarily disable breakpoints while keeping their configuration.

Related tools: setBreakpoint, deleteBreakpoint, listBreakpoints

Set a memory watchpoint to stop when memory is read or written.

Watchpoints are powerful for debugging:

• "Why is this value changing?" → Use store watchpoint

• "What's reading this address?" → Use load watchpoint

• "Track all access to this region" → Use both

Range can be single address or address range (e.g., $D800-$DBFF for color RAM).

Related tools: deleteBreakpoint, listWatchpoints, continue

List all active memory watchpoints.

Shows watchpoint IDs, address ranges, type (load/store), and status.

Related tools: setWatchpoint, deleteBreakpoint, listBreakpoints

Run execution until a specific address is reached.

Sets a temporary breakpoint at the target address and continues execution. The breakpoint is automatically deleted when hit.

Use for:

• "Run until this function" → runTo(functionAddress)

• "Skip to the end of this loop" → runTo(addressAfterLoop)

Related tools: continue, step, setBreakpoint

Disassemble 6502 machine code at a memory address.

Returns human-readable assembly instructions with:

• Address and raw bytes

• Mnemonic and operand

• Branch target addresses (for branch instructions)

• Known KERNAL/BASIC labels

Options:

• address: Start address (default: current PC)

• count: Number of instructions (default: 10)

Related tools: readMemory, getRegisters, step

Save the complete machine state to a file.

Creates a VICE snapshot file containing:

• All memory (RAM, I/O states)

• CPU registers

• VIC-II, SID, CIA states

• Disk drive state (if attached)

Use to:

• Save state before risky debugging

• Create restore points

• Share exact machine state

Related tools: loadSnapshot

Load a previously saved machine state from a file.

Restores complete machine state including memory, registers, and peripheral states.

Warning: This completely replaces the current state!

Related tools: saveSnapshot

Load and optionally run a program file.

Supports PRG, D64, T64, and other C64 file formats. For disk images, can specify which file to run.

Options:

• run: If true (default), starts execution after loading

• fileIndex: For disk images, which file to load (0 = first)

Related tools: reset, status, setBreakpoint

Read the C64 screen memory and return it as interpreted text.

Converts PETSCII screen codes to readable ASCII. Returns 25 lines of 40 characters.

Use this instead of readMemory($0400) when you want to see what's displayed on screen.

Note: This reads from the current screen RAM location (may not be $0400 if the program moved it). In bitmap modes, the data won't represent text.

Options:

• format: "full" (default) returns all 25 lines, "summary" returns only non-empty lines

• includeRaw: Also return raw screen codes (default: false)

Related tools: readColorRam, readVicState, readMemory

Read color RAM ($D800-$DBE7) and return color values with names.

Color RAM determines the foreground color of each character on screen.

Returns:

• 25x40 grid of color values (0-15) with names

• Summary of colors used

Related tools: readScreen, readVicState

Read the full VIC-II state with interpreted values.

Returns all VIC-II registers with semantic meaning:

• Border and background colors (with names)

• Graphics mode (text, bitmap, multicolor, etc.)

• Screen and character memory locations

• Scroll values

• Raster position

• Sprite enable bits

This is the high-level view of the video chip. Use for understanding display configuration.

Related tools: readScreen, readSprites, readMemory (for $D000-$D02E)

Read state of all 8 hardware sprites with interpreted values.

Returns for each sprite:

• Position (X, Y) with visibility check

• Color (with name)

• Enable status

• Multicolor mode

• X/Y expansion (double size)

• Priority (in front of / behind background)

• Data pointer address

Use this to debug sprite issues like:

• "Why is my sprite invisible?" → check enabled, position, pointer

• "Wrong colors?" → check multicolor mode and color registers

• "Wrong size?" → check expand flags

Options:

• enabledOnly: Only return enabled sprites (default: false)

Related tools: readVicState, readMemory (for sprite data)

Capture the current VICE display as image data.

Returns the raw display buffer with:

• Pixel data (indexed 8-bit palette colors)

• Display dimensions and visible area

• Current palette RGB values

The data can be used to understand what's currently on screen visually. For text mode screens, readScreen provides a simpler text representation.

Options:

• includePalette: Also return the color palette (default: true)

Related tools: readScreen, readVicState

Render the current screen as ASCII art representation.

Creates a visual representation of the screen using ASCII characters to approximate the colors and content visible on the C64 display.

This is useful for quick visual debugging without image handling. For actual screen text, use readScreen instead.

Options:

• width: Output width in characters (default: 80)

• height: Output height in lines (default: 50)

• charset: Character set to use for shading (default: " .:-=+*#%@")

Related tools: readScreen, screenshot, readVicState