Which integrations are available for this server?

Enables autonomous debugging of Commodore 64 programs through the VICE emulator, providing semantic interpretation of 6502 assembly code, memory operations, breakpoint management, VIC-II graphics state analysis, sprite debugging, and PETSCII screen text decoding.

How do I use VICE C64 Emulator MCP Server?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@VICE C64 Emulator MCP Server load my game.prg and set a breakpoint at the main loop" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

vice-mcp

A Model Context Protocol (MCP) server for autonomous C64 debugging via the VICE emulator.

What is this?

vice-mcp bridges AI agents to the VICE Commodore 64 emulator, enabling autonomous debugging of 6502 assembly programs. Unlike raw protocol wrappers, it provides a semantic layer that interprets C64-specific data structures and returns meaningful, actionable information.

Why this exists:

AI agents need more than hex dumps—they need interpreted data with context
Debugging C64 code requires understanding VIC-II banks, PETSCII encoding, sprite pointers, and memory layouts
Every response includes hints suggesting next steps and related tools

Key differentiators:

Semantic output: readScreen returns text, not screen codes. readVicState explains graphics modes, not register bits.
Actionable hints: Every response suggests what to do next
Cross-references: Tools point to related tools for common workflows
Agent-friendly errors: Clear error codes and recovery suggestions

Prerequisites

Node.js 18 or later
VICE emulator with binary monitor enabled

Starting VICE with Binary Monitor

# x64sc is the accurate C64 emulator (recommended)
x64sc -binarymonitor -binarymonitoraddress ip4://127.0.0.1:6502

# Or with x64 (faster, less accurate)
x64 -binarymonitor -binarymonitoraddress ip4://127.0.0.1:6502

The binary monitor listens on port 6502 by default.

Installation

From npm (when published)

npx @simen/vice-mcp

From GitHub

npx github:simen/vice-mcp

Local Development

git clone https://github.com/simen/vice-mcp.git
cd vice-mcp
npm install
npm run build
npm start

Claude Code Installation

The quickest way to get started with Claude Code:

1. Start VICE with binary monitor:

x64sc -binarymonitor -binarymonitoraddress ip4://127.0.0.1:6502

2. Add the MCP server:

claude mcp add vice-mcp -- npx github:simen/vice-mcp

3. Restart Claude Code to load the new MCP server.

That's it! You can now ask Claude Code to debug your C64 programs.

Manual Configuration

Alternatively, add to ~/.claude/claude_desktop_config.json:

{
  "mcpServers": {
    "vice-mcp": {
      "command": "npx",
      "args": ["github:simen/vice-mcp"]
    }
  }
}

Configuration

Add to your MCP client configuration (e.g., Claude Desktop, Cursor, or custom agent):

{
  "mcpServers": {
    "vice": {
      "command": "npx",
      "args": ["@simen/vice-mcp"]
    }
  }
}

Or for local development:

{
  "mcpServers": {
    "vice": {
      "command": "node",
      "args": ["/path/to/vice-mcp/dist/index.js"]
    }
  }
}

Tool Reference

Connection & Status

Tool	Description
`connect`	Connect to VICE (default: 127.0.0.1:6502)
`disconnect`	Disconnect from VICE
`status`	Get connection state and emulation status

Memory Operations

Tool	Description
`readMemory`	Read raw bytes with hex dump and ASCII
`writeMemory`	Write bytes to memory

CPU & Execution

Tool	Description
`getRegisters`	Get A, X, Y, SP, PC, and flags (interpreted)
`step`	Single-step execution (with step-over option)
`continue`	Resume execution
`reset`	Soft or hard reset
`runTo`	Run until specific address (temporary breakpoint)
`disassemble`	Disassemble 6502 code with KERNAL labels

Breakpoints & Watchpoints

Tool	Description
`setBreakpoint`	Set execution breakpoint
`deleteBreakpoint`	Remove breakpoint or watchpoint
`listBreakpoints`	List all breakpoints
`toggleBreakpoint`	Enable/disable breakpoint
`setWatchpoint`	Set memory read/write watchpoint
`listWatchpoints`	List all watchpoints

Semantic Layer (Interpreted C64 Data)

Tool	Description
`readScreen`	Get screen as text (PETSCII decoded) with summary mode
`readColorRam`	Get color RAM with color names and usage stats
`readVicState`	Full VIC-II state: graphics mode, colors, banks, sprites
`readSprites`	All 8 sprites: position, visibility, colors, pointers

Visual Feedback

Tool	Description
`screenshot`	Capture display buffer with palette
`renderScreen`	ASCII art rendering of display

State Management

Tool	Description
`saveSnapshot`	Save complete machine state to file
`loadSnapshot`	Load machine state from file
`loadProgram`	Load and optionally run PRG/D64/T64 files

Example Usage

Basic Debugging Session

1. connect()                    → Establish connection
2. loadProgram("game.prg")      → Load the program
3. setBreakpoint(0x0810)        → Break at main loop
4. continue()                   → Run until breakpoint
5. getRegisters()               → Check CPU state
6. readScreen()                 → See what's on screen
7. step(count: 5)               → Execute 5 instructions
8. disassemble()                → See code at current PC

Debugging Sprite Issues

1. readVicState()               → Check sprite enable bits
2. readSprites(enabledOnly: true) → Get enabled sprite details
   → Response includes visibility check and position analysis
3. If sprite not visible, hint tells you why (off-screen, wrong bank, etc.)

Memory Watchpoint Workflow

1. setWatchpoint(startAddress: 0x0400, type: "store")
   → Watch for writes to screen RAM
2. continue()
   → Execution stops when something writes to screen
3. getRegisters()
   → See PC to find the code that wrote
4. disassemble()
   → Understand what the code is doing

State Checkpoint Pattern

1. saveSnapshot("before-test.vsf")  → Save state
2. [Make changes, test things]
3. loadSnapshot("before-test.vsf")  → Restore to known state

Response Format

All responses include:

Structured data with value and hex representations
_meta block with connection state
hint field with contextual next steps

Example getRegisters response:

{
  "a": { "value": 65, "hex": "$41" },
  "x": { "value": 0, "hex": "$00" },
  "y": { "value": 0, "hex": "$00" },
  "sp": { "value": 243, "hex": "$f3", "stackTop": "$01f3" },
  "pc": { "value": 2049, "hex": "$0801" },
  "flags": {
    "negative": false,
    "overflow": false,
    "zero": false,
    "carry": false,
    "string": "nv-bdizc"
  },
  "hint": "CPU state looks normal",
  "_meta": {
    "connected": true,
    "running": false,
    "host": "127.0.0.1",
    "port": 6502
  }
}

Architecture Overview

┌─────────────────────────────────────────────────────────┐
│                    MCP Client (Agent)                    │
└─────────────────────────────────────────────────────────┘
                            │
                            │ MCP Protocol (stdio)
                            ▼
┌─────────────────────────────────────────────────────────┐
│                     src/index.ts                         │
│                    (MCP Server)                          │
│  ┌─────────────────────────────────────────────────┐    │
│  │              Tool Handlers (24 tools)            │    │
│  │  • Connection: connect, disconnect, status       │    │
│  │  • Memory: readMemory, writeMemory              │    │
│  │  • CPU: getRegisters, step, continue, reset     │    │
│  │  • Breakpoints: set, delete, list, toggle       │    │
│  │  • Watchpoints: set, list                       │    │
│  │  • Semantic: readScreen, readVicState, etc.     │    │
│  │  • Visual: screenshot, renderScreen            │    │
│  │  • State: saveSnapshot, loadSnapshot, loadPrg   │    │
│  └─────────────────────────────────────────────────┘    │
└─────────────────────────────────────────────────────────┘
                            │
                            │ Uses
                            ▼
┌─────────────────────────────────────────────────────────┐
│                 src/protocol/client.ts                   │
│                    (ViceClient)                          │
│  • TCP socket connection to VICE                        │
│  • Binary protocol encoding/decoding                    │
│  • Request/response correlation                         │
│  • Checkpoint (breakpoint/watchpoint) tracking          │
└─────────────────────────────────────────────────────────┘
                            │
                            │ TCP Socket
                            ▼
┌─────────────────────────────────────────────────────────┐
│                 VICE Binary Monitor                      │
│                   (Port 6502)                            │
└─────────────────────────────────────────────────────────┘

Key Files

File	Purpose
`src/index.ts`	MCP server, tool definitions, semantic layer
`src/protocol/client.ts`	VICE binary monitor client
`src/protocol/types.ts`	Protocol constants and types
`src/utils/c64.ts`	C64 utilities (PETSCII, colors, VIC banks)
`src/utils/disasm.ts`	6502 disassembler with all addressing modes

Design Principles

Semantic over raw: Return interpreted data, not just bytes
Hints everywhere: Every response suggests next actions
Cross-references: Tools reference related tools
Fail informatively: Errors explain what went wrong and how to fix it
Agent-first: Designed for autonomous operation, not human CLI use

Protocol Reference

vice-mcp implements the VICE Binary Monitor Protocol. Key commands used:

Code	Command	Purpose
0x01	MemoryGet	Read memory
0x02	MemorySet	Write memory
0x12	CheckpointSet	Create breakpoint/watchpoint
0x13	CheckpointDelete	Remove checkpoint
0x15	CheckpointToggle	Enable/disable checkpoint
0x31	RegistersGet	Read CPU registers
0x41	Dump	Save snapshot
0x42	Undump	Load snapshot
0x81	Continue	Resume execution
0x82	Step	Single-step
0x84	DisplayGet	Capture screen
0x91	PaletteGet	Get color palette
0xdd	AutoStart	Load and run program

License

MIT

VICE C64 Emulator MCP Server