ViceMCP

ViceMCP is an MCP server that exposes the VICE Commodore emulator's debugging and memory-access capabilities to MCP clients and AI assistants. It enables powerful memory operations (read, write, search, and compare), CPU control (get/set registers, step, continue, reset), and advanced debugging workflows via batch commands for higher throughput. With this server, you can integrate AI-assisted debugging workflows for multiple Commodore machines (C64, C128, VIC-20, PET, Plus/4, and more) and issue complex sequences of emulator operations in a single request. The included batch example demonstrates how 10x performance can be achieved by combining multiple memory operations into one batch call. To interact with the server, configure an MCP client (like Claude Code CLI) to connect to the running ViceMCP instance and issue the documented MCP commands such as read_memory, write_memory, set_checkpoint, get_registers, and step.

Typical usage flows: start the ViceMCP server, then use your MCP client to connect and issue memory or CPU commands, or to execute pre-defined batch scripts for common tasks like initializing screen borders, loading values into memory, or scanning memory regions for specific patterns. The tooling is designed to be accessible from natural-language prompts and scripted via JSON payloads, enabling you to automate debugging sessions and iterate quickly on 8-bit Commodore software.

Prerequisites:

• .NET 9.0 SDK or later installed on your platform
• (Optional) Docker if you prefer running a containerized instance

Installation steps (from source):

1. Install .NET 9.0 SDK

   • Windows: download from https://dotnet.microsoft.com/download/dotnet/9.0
   • macOS/Linux: follow the official installation instructions for your distro

2. Clone the repository and build

git clone https://github.com/barryw/ViceMCP.git
cd ViceMCP

# Build the project (Release)
dotnet build -c Release

3. Run the server (from built artifacts)

# If the server DLL is at bin/Release/net9.0/ViceMCP.dll
dotnet bin/Release/net9.0/ViceMCP.dll

4. Optional: Run via Docker (quick test)

docker run -it ghcr.io/barryw/vicemcp:latest

5. Configure MCP client (example with Claude Code CLI)

claude mcp add vicemcp "dotnet bin/Release/net9.0/ViceMCP.dll"

Prerequisites recap:

• A supported .NET runtime (or Docker image as an alternative)
• Access to the ViceMCP binary or container image
• Administrative access to expose the needed ports if required by your environment

Notes and tips:

• The server provides native AOT builds without requiring a separate runtime in some distributions; if you use the Release binaries, ensure the appropriate dependencies are present on the host.
• If you choose to run via Docker, you can map VICE's binary monitor port (e.g., 6502) via environment variables or volume mounts as demonstrated in the Docker examples.
• For Claude/Code CLI integration, you can pass a full command string to mcp add, including docker run invocations or local paths to the built ViceMCP binary.
• When running in multi-machine environments, you can define multiple MCP servers by duplicating the mcpServers entry with distinct names (e.g., vicemcp64, vicemcp128) and unique connection parameters.
• If you encounter permission or path issues, verify that the working directory contains the built ViceMCP.dll and that any referenced VICE binaries (for local debugging) are accessible via the configured VICE_BIN_PATH.
• Batch commands significantly improve throughput by aggregating memory operations; consider using execute_batch for large-scale memory edits or scans.