CBM MCP: VICE Monitor

An MCP server that lets AI agents debug Commodore software in a locally running VICE emulator, through VICE's text remote monitor.

It runs locally over stdio, next to VICE. Nothing is hosted, and the unauthenticated VICE monitor should never be exposed beyond loopback.

What You Can Do

The server covers the command families of the VICE monitor, so an agent can:

• Inspect CPU registers, memory (as hex, PETSCII or screen codes), the text screen, call stacks, memory banks and I/O state.
• Disassemble and assemble code, and annotate it with labels and comments.
• Control execution by stepping, running until a condition, setting breakpoints, watchpoints and tracepoints, and resuming or resetting the machine.
• Modify state by writing registers and memory, filling, moving, comparing and searching memory, and typing on the emulated keyboard.
• Work with media and files such as disk images, programs, snapshots and binary data, as well as VICE settings and resources.
• Profile and trace with CPU history and profiling data, where the VICE build supports it.
• Export graphics such as sprites and character sets as images, and capture screenshots.

The available commands depend on the VICE version, the emulated machine, and build options. The server also sends debugging guidance to the agent, covering safe inspection, memory banking, side effects and cleanup. A command catalog documents the details.

Quick Start

You need Node.js 24+ and a VICE emulator with its text remote monitor enabled.

1. Start VICE with the text monitor (the executable name depends on your installation and machine; do not use the binary monitor):

   x64sc -remotemonitor -remotemonitoraddress ip4://127.0.0.1:6510
   

2. Add the server to your MCP client's configuration:

   {
       "servers": {
           "cbm-mcp": {
               "type": "stdio",
               "command": "npx",
               "args": ["--yes", "cbm-mcp@latest"]
           }
       }
   }
   

3. Ask your agent, for example: "Connect to VICE and show the CPU registers."

Harnesses differ in where they keep this configuration, and some use mcpServers instead of servers. Pin a version instead of latest for repeatable setups.

Configuration

Optional environment variables, set in the client's env object:

Invalid settings fail startup with a diagnostic on stderr. Starting the MCP does not connect to or pause VICE.

Agent Skill via APM

This repository is also an APM package. It ships the cbm-mcp agent skill with C64, VIC-II and 6510 reference material, which complements the general guidance the server already provides. Install it into a project with:

apm install thred/cbm-mcp

APM deploys the skill for your configured agent targets. The MCP server entry in apm.yml launches a local build (dist/stdio.js), so it only works inside a source checkout; configure the server for other projects as described in Quick Start.

Safety

• Connecting to the monitor pauses emulation, and it stays paused until the agent resumes it deliberately.
• Disconnecting never quits VICE. Only one monitor client can be attached at a time, so use one controller at a time.
• Reading I/O can have side effects, which VICE's monitor can be told to suppress. Stepping and writes change machine state and are not undone automatically. A timeout cannot guarantee that a command did not execute, so state-changing operations should not be retried blindly.
• Some capabilities reset or quit the emulator, write to disks, access host files or run monitor scripts. Host paths are interpreted by VICE without a sandbox. Use your MCP client's approval controls; tool annotations and confirmation fields are not a security boundary, and only trusted clients and files should be used.

Development

Install from source and run the checks:

npm install
npm run build
npm test
npm run test:typecheck

To use a checkout instead of the npm package, configure the client with "command": "node" and "args": ["/absolute/path/to/cbm-mcp/dist/cli.js"]. Launch the executable directly rather than through npm start, whose banners would corrupt the MCP stream on stdout. npm run dev starts the TypeScript sources for manual runs. Restart the server in the client after rebuilding.

The default tests use an in-process fixture instead of VICE. With VICE's text monitor running, npm run test:live additionally runs read-only checks against the real emulator. It pauses the emulator and leaves it paused. The live test is skipped by default.

If a new connection times out even though the port is listening, disconnect other monitor clients. VICE can also retain a stale session while paused: leave the monitor or resume once in VICE's UI, then reconnect.

The source layout is small: the monitor connection (src/vice/monitor-client.ts) is independent of MCP, the tools live in src/vice/monitor-tools.ts, the server factory is in src/server.ts, and src/cli.ts and src/stdio.ts provide the stdio executable. Other MCP transports can reuse the server factory; a network-facing transport needs proper authentication.