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:
readScreenreturns text, not screen codes.readVicStateexplains 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
valueandhexrepresentations _metablock with connection statehintfield 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