by chrisgleissner
Control and program a Commodore 64 – either real C64 Ultimate hardware or the VICE emulator – from an AI client using a unified MCP interface that exposes memory, graphics, sound, disk, printer and system operations.
C64 Bridge provides an MCP server that gives AI agents a single entry point to drive program execution, read/write memory, render graphics, play SID music, manage drives, printers and more on a Commodore 64. It works with real C64 Ultimate/Ultimate 64 hardware and can switch at runtime to a VICE emulator, allowing the same workflow across both platforms.
npx -y c64bridge
.c64bridge.json or ~/.c64bridge.json) or by setting environment variables such as C64_MODE, C64U_HOST, VICE_BINARY, etc.stdio entry point. The client can then call tools like c64_program, c64_memory, c64_graphics, c64_sound, etc.c64_select_backend.Q: Do I need a C64 Ultimate to use the server? A: No. The server works with VICE as a fully‑featured emulator. If a hardware device is present, you can switch to it at runtime.
Q: Which operating systems are supported? A: Linux, macOS and Windows. The npm package includes pre‑built binaries for VICE and works with the C64 Ultimate network API.
Q: How are environment variables used?
A: Variables like C64_MODE, C64U_HOST, VICE_BINARY, LOG_LEVEL, etc., override corresponding JSON configuration fields, allowing quick per‑session changes without editing files.
Q: Can I integrate C64 Bridge into my own application?
A: Yes. The server exposes a standard MCP stdio interface; you can spawn it as a child process and communicate using the generated tool schemas.
Q: Is there a way to run the server without installing Node globally?
A: You can use npx which fetches the package on‑the‑fly, so no global install is required.

Your AI Command Bridge for the Commodore 64.
C64 Bridge is an MCP server for controlling and working with a Commodore 64 from an AI client.
It lets you run programs, read and write memory, render graphics, and play sound on a real Commodore 64 Ultimate or Ultimate 64. You can also switch to a VICE emulator session at any time, so the same MCP conversation works with both hardware and emulator.
It is built on the official TypeScript @modelcontextprotocol/sdk and supports both stdio for local AI integration and an optional HTTP bridge for manual inspection.
C64 Bridge is listed in the Official MCP Registry.
C64 Bridge gives an AI agent one place to drive program execution, memory access, graphics, sound, storage, printer workflows, and knowledge retrieval for a Commodore 64 environment.
The core workflow is simple:
c64_program, c64_memory, c64_graphics, and c64_sound.c64_select_backend when both are configured.c64u and emulator viceIf you want the shortest path, do these four things:
Linux (Ubuntu or Debian):
Recommended:
sudo apt update
sudo apt install -y curl ca-certificates
curl -fsSL https://deb.nodesource.com/setup_24.x | sudo -E bash -
sudo apt install -y nodejs
Fallback:
sudo apt install -y nodejs npm
macOS:
brew install node@24
brew link --overwrite node@24
Windows:
# winget
winget install OpenJS.NodeJS.LTS
# or Chocolatey
choco install nodejs-lts -y
Verify the installation:
node --version
Expected result: v24.x
Use one of the following entry points.
Run from npx with zero setup:
npx -y c64bridge@latest
Run from a local npm install:
mkdir -p ~/c64bridge && cd ~/c64bridge
npm init -y
npm install c64bridge
node ./node_modules/c64bridge/dist/index.js
Run from source for development or testing:
git clone https://github.com/chrisgleissner/c64bridge.git
cd c64bridge
./build install
npm start
On startup, the server probes the selected target, performs connectivity checks, and then announces that it is running on stdio.
The server can run against:
The detailed lookup order, merge rules, backend examples, and override model are in the Configuration section below.
C64 Bridge ships a single canonical stdio entry point that every MCP client uses:
stdio server, with the environment variables documented in Runtime Environment Variable Reference and the registry manifest in mcp.json.The startup command is the same across clients: npx -y c64bridge@latest for the published package, or node scripts/start.mjs from a local checkout. Backend selection (c64u vs vice) and credentials live in the shared Configuration files and environment variables — clients only need to know the command.
The server reads configuration in this order:
C64BRIDGE_CONFIG, if it points to a config file.c64bridge.json in the project root~/.c64bridge.json in the home directoryConfiguration is merged per backend section while scanning those files in order.
c64u section supplies the C64 Ultimate configuration.vice section supplies the VICE configuration..c64bridge.json to define c64u while ~/.c64bridge.json defines vice, with both backends available at runtime.Use this for a C64 Ultimate or Ultimate 64:
{
"c64u": {
"host": "c64u",
"port": 80,
"networkPassword": "secret"
}
}
c64u:80 with no network password.networkPassword is only needed when you enabled a password in the C64 Ultimate network settings.C64U_HOST, C64U_PORT, and C64U_PASSWORD override the configured host, port, and network password.Use this for managed VICE launches:
{
"vice": {
"exe": "/usr/bin/x64sc",
"directory": "/usr/local/share/vice"
}
}
directory is optional. When omitted, C64 Bridge auto-detects a VICE resource directory by looking for the standard C64 ROM set near the emulator binary and in common system locations.VICE_BINARY, VICE_DIRECTORY, VICE_HOST, VICE_PORT, VICE_VISIBLE, VICE_WARP, and VICE_ARGS override managed VICE startup without editing config files./usr/local/bin/x64sc when present, then falls back to x64sc or x64 on PATH so the same setup remains portable across operating systems.[!NOTE] VICE supports only the operations marked with a VICE checkmark in the MCP API Reference. Unsupported operations return
unsupported_platform.
When both c64u and vice are configured, C64 Bridge starts with one active backend and keeps the other available for runtime switching.
C64_MODE chooses the initial backend: c64u or vicec64_select_backend switches backends without restarting the MCP serverc64://platform/status reports the active backend and the full configured backend setuse vice, vice: run this program, use c64u, or run this on the real machinePrompt illustration (issued via Copilot in VS Code, using GPT 5.4 Medium):
c64u: write a small BASIC program that clears the screen and prints HELLO C64U
vice: write a small BASIC program that clears the screen and prints HELLO VICE
The screenshots below were captured from actual backend bitmap responses after those prompts ran, using the same c64_graphics capture_frame MCP tool on both backends. The C64U implementation captures streamed video frames, while the VICE implementation captures and normalizes the emulator display frame. Both images were then verified optically against the expected text with the C64 character generator, and both matched exactly.
| Backend | Screenshot |
|---|---|
| C64 Ultimate | ![]() |
| VICE | ![]() |
This section covers the GitHub Copilot integration that ships with VS Code. For the Claude Code VS Code plugin, see Claude Code — it reads .mcp.json, not .vscode/mcp.json.
If this repository is checked out locally, open the prepared .vscode/mcp.json.
Otherwise, put the following into your own .vscode/mcp.json:
{
"servers": {
"c64bridge": {
"command": "npx",
"args": [
"-y",
"c64bridge@latest"
]
}
}
}
Then click the start button shown above the c64bridge entry.
Your MCP server should now be running:

For more details, see the official VS Code MCP Server documentation.
After the server is running, switch to the C64 agent in VS Code.
This agent is preconfigured for Commodore 64 work. It steers Copilot toward c64bridge workflows for BASIC, 6502 assembly, SID audio, VIC-II graphics, memory inspection, disk operations, printing, streaming, and device control.

You can add env entries in .vscode/mcp.json to select a config file, override C64 Ultimate connection details, or force an initial backend:
{
"servers": {
"c64bridge": {
"command": "npx",
"args": [
"-y",
"c64bridge@latest"
],
"env": {
"C64BRIDGE_CONFIG": "/home/you/.c64bridge.json",
"C64U_HOST": "192.168.1.99",
"C64U_PORT": "80",
"C64U_PASSWORD": "secret",
"C64_MODE": "c64u",
"LOG_LEVEL": "debug"
}
}
}
}
C64BRIDGE_CONFIG points to a specific config fileC64U_HOST, C64U_PORT, and C64U_PASSWORD override the C64 Ultimate connection without editing config filesC64_MODE forces the initial backend to c64u or viceLOG_LEVEL=debug enables verbose loggingEvery runtime environment variable documented in the root mcp.json can be supplied by your MCP client configuration, including .vscode/mcp.json under servers.c64bridge.env.
When an environment variable maps to a JSON config field, the override order is always:
C64BRIDGE_CONFIG, the repo .c64bridge.json, then ~/.c64bridge.jsonWhen an environment variable has no JSON config equivalent, the order is:
That rule applies uniformly across the documented runtime environment variables below.
Example: visible VICE with a specific ROM or resource directory, plus a hardware fallback that can still be selected instantly at runtime:
{
"servers": {
"c64bridge": {
"command": "node",
"args": ["${workspaceFolder}/scripts/start.mjs"],
"type": "stdio",
"env": {
"C64_MODE": "vice",
"C64U_HOST": "c64u",
"C64U_PORT": "80",
"VICE_BINARY": "/usr/local/bin/x64sc",
"VICE_DIRECTORY": "/usr/local/share/vice",
"VICE_VISIBLE": "true",
"VICE_WARP": "false"
}
}
}
}
Example: keep JSON config files for backend endpoints, but override diagnostics, polling, and RAG behavior from VS Code:
{
"servers": {
"c64bridge": {
"command": "node",
"args": ["${workspaceFolder}/scripts/start.mjs"],
"type": "stdio",
"env": {
"C64BRIDGE_CONFIG": "/home/you/.c64bridge.json",
"LOG_LEVEL": "debug",
"C64BRIDGE_POLL_MAX_MS": "8000",
"C64BRIDGE_POLL_INTERVAL_MS": "200",
"RAG_BUILD_ON_START": "1",
"RAG_EMBEDDINGS_DIR": "/home/you/c64bridge-data"
}
}
}
}
Every runtime environment variable documented in mcp.json can be set in your MCP client configuration, including .vscode/mcp.json under servers.c64bridge.env.
| Variable | Default | JSON Config Key | Description |
|---|---|---|---|
C64_MODE |
c64u | — | Select active backend (c64u for Ultimate hardware, vice for emulator) |
C64_TASK_STATE_FILE |
auto | — | Override the path used to persist MCP background-task state |
C64BRIDGE_CONFIG |
~/.c64bridge.json | config path | Path to configuration JSON |
C64BRIDGE_DIAGNOSTICS_DIR |
~/.c64bridge/diagnostics | — | Override the directory where persistent MCP diagnostics files are written |
C64BRIDGE_DISABLE_DIAGNOSTICS |
0 | — | Set to 1 to disable persistent diagnostics logging |
C64BRIDGE_POLL_INTERVAL_MS |
200 | — | Interval between screen polls during program-output validation in normal runtime mode |
C64BRIDGE_POLL_MAX_MS |
2000 | — | Maximum time to poll for program-output validation before timing out in normal runtime mode |
C64BRIDGE_POLL_STABILIZE_MS |
100 | — | Extra settle time after a successful poll match before considering output stable |
LOG_LEVEL |
info | — | Logger verbosity (debug, info, warn, error) |
| Variable | Default | JSON Config Key | Description |
|---|---|---|---|
C64U_HOST |
c64u | c64u.host | Override the C64 Ultimate host name or IP address |
C64U_PASSWORD |
c64u.networkPassword | Override the C64 Ultimate network password sent as X-Password | |
C64U_PORT |
80 | c64u.port | Override the C64 Ultimate REST port |
| Variable | Default | JSON Config Key | Description |
|---|---|---|---|
DISABLE_XVFB |
0 | — | Set to 1 to disable Xvfb fallback and use the current display only |
FORCE_XVFB |
0 | — | Set to 1 to force managed VICE launches to run under Xvfb |
VICE_ARGS |
vice.args | Extra command-line arguments forwarded to managed VICE launches | |
VICE_BINARY |
x64sc | vice.exe | VICE binary to launch for managed emulator sessions and audio capture; automatic search is used only when this override is missing or invalid |
VICE_DIRECTORY |
auto-detect | vice.directory | Override the VICE resource directory used for ROM and UI asset discovery; automatic search is used only when this override is missing or invalid |
VICE_HOST |
127.0.0.1 | vice.host | Override the VICE Binary Monitor host |
VICE_PORT |
6502 | vice.port | Override the VICE Binary Monitor port |
VICE_VISIBLE |
true | vice.visible | Launch VICE visibly on the desktop instead of headless/Xvfb when possible |
VICE_WARP |
false when visible, true when headless | vice.warp | Enable warp mode for managed VICE sessions |
VICE_XVFB_DISPLAY |
:99 | — | Display number to use when managed VICE launches under Xvfb |
| Variable | Default | JSON Config Key | Description |
|---|---|---|---|
VICE_LIMIT_CYCLES |
120000000 | — | Maximum CPU cycles to render when VICE generates audio |
VICE_MODE |
ntsc | — | Default video standard for VICE audio capture (ntsc|pal) |
VICE_RUN_TIMEOUT_MS |
10000 | — | Timeout for headless VICE runs in milliseconds |
| Variable | Default | JSON Config Key | Description |
|---|---|---|---|
SIDPLAY_BINARY |
sidplayfp | — | sidplayfp binary to launch when generating audio |
SIDPLAY_LIMIT_CYCLES |
120000000 | — | Maximum CPU cycles to render when sidplayfp generates audio |
SIDPLAY_MODE |
ntsc | — | Default SID playback mode (ntsc|pal) |
SIDPLAYFP_BINARY |
— | Legacy alias for SIDPLAY_BINARY (sidplayfp executable name) |
| Variable | Default | JSON Config Key | Description |
|---|---|---|---|
GITHUB_TOKEN |
— | Personal access token used for optional RAG discovery against GitHub | |
RAG_BUILD_ON_START |
0 | — | Set to 1 to rebuild embeddings on server start |
RAG_DISCOVER_FORCE_REFRESH |
0 | — | Set to 1 to ignore cached discovery results when fetching external docs |
RAG_DOC_FILES |
— | Comma-separated extra docs to include in RAG | |
RAG_EMBEDDINGS_DIR |
data | — | Directory containing RAG embedding JSON files |
RAG_REINDEX_INTERVAL_MS |
0 | — | Periodic reindex interval in ms (0 disables) |
| Variable | Default | JSON Config Key | Description |
|---|---|---|---|
C64_TEST_TARGET |
— | Overrides integration tests to hit mock or real hardware (mock|real) |
Claude Code is supported as a first-class MCP client. It uses the same canonical start command and the same backend Configuration files and environment variables as every other client — only the discovery file differs.
Claude Code CLI — register the published server in one command:
claude mcp add c64bridge -- npx -y c64bridge@latest
Use --scope user to make it available across all your projects, or --scope project to write a .mcp.json next to the current repo. Backend selection (c64u vs vice), host, port, and password come from the same files documented in Configuration; per-shell overrides come from the variables in Runtime Environment Variable Reference.
Project-scoped discovery — this repository ships a checked-in .mcp.json that points Claude Code at the local source via node scripts/start.mjs. When you open the repo with claude (CLI or VS Code plugin), Claude Code prompts to enable the project-scoped server on first run. Approve it once and the c64_* tools become discoverable in that workspace.
Claude Code VS Code plugin — the plugin reads the same .mcp.json and the same user-scope claude mcp add registrations as the CLI. No extra setup is required beyond installing the plugin and approving the project server prompt. The existing .vscode/mcp.json is read by GitHub Copilot, not by Claude Code; the two files coexist without conflict because they target different clients with different config schemas.
Verify it works — after registration, run claude mcp list (CLI) or open the MCP panel (plugin) and look for c64bridge. Then ask Claude Code something like “use vice: write a small BASIC program that clears the screen and prints HELLO CLAUDE” — it should call c64_select_backend and c64_program directly. If tools do not appear, confirm Node 24+ is on PATH, that the server was approved at the requested scope, and that the backend is reachable per the Configuration section.
Compose a children’s song with ChatGPT and VS Code:

Then render PETSCII art for it:

This is representative of the intended workflow:
c64_program, c64_graphics, and c64_sound to execute it.stdio.# Upload and run BASIC
curl -s -X POST -H 'Content-Type: application/json' \
-d '{"op":"upload_run_basic","program":"10 PRINT \"HELLO\"\n20 GOTO 10"}' \
http://localhost:8000/tools/c64_program | jq
# Read current screen (PETSCII→ASCII)
curl -s -X POST -H 'Content-Type: application/json' \
-d '{"op":"read_screen"}' \
http://localhost:8000/tools/c64_memory | jq
# Reset the machine
curl -s -X POST -H 'Content-Type: application/json' \
-d '{"op":"reset"}' \
http://localhost:8000/tools/c64_system
The ./build script at the project root wraps all development tasks behind a single, self-documented interface:
./build --help # full command reference
./build # install + build + test matrix (full CI run)
./build --skip-tests # install + build only
./build build # TypeScript compile + doc generation
./build test # integration tests (mock backend)
./build test --real # test against real hardware
./build test --platform vice --target mock # single test leg
./build test:matrix # full matrix (c64u/mock · vice/mock · vice/device)
./build coverage # merged coverage report
./build coverage:single --platform c64u --target mock
./build check # build + test matrix (no install)
./build rag:rebuild # rebuild RAG embeddings
./build release --version 1.2.3 # prepare a release
Starting the MCP server is not managed by
./build. Usenpm start(from source) ornpx -y c64bridge@latest(published package) as shown in the Quick Start section above.
The repository contains an auto-generated static mirror of the MCP server interface in the ./mcp folder.
This allows agents to inspect the available tools, resources, prompts, and schemas without connecting to the server.
This MCP server exposes 17 tools, 26 resources, and 10 prompts for controlling your Commodore 64.
Address range convention: address + length means start address plus byte count; startAddress + endAddress means inclusive bounds.
Execute multiple c64bridge tool calls in a single request. Reduces latency for multi-step workflows.
No operations defined.
Grouped entry point for configuration reads/writes, diagnostics, and snapshots.
| Operation | Description | Required Inputs | Optional Inputs | Notes | C64U | VICE |
|---|---|---|---|---|---|---|
batch_update |
Apply multiple configuration updates in a single request. | — | — | — | ✅ | ✅ |
diff |
Compare the current configuration with a snapshot. | path |
— | — | ✅ | ✅ |
get |
Read a configuration category or specific item. | category |
item |
— | ✅ | ✅ |
info |
Retrieve Ultimate hardware information and status. | — | — | — | ✅ | ✅ |
list |
List configuration categories reported by the firmware. | — | — | — | ✅ | ✅ |
load_flash |
Load configuration from flash storage. | — | — | — | ✅ | |
read_debugreg |
Read the Ultimate debug register ($D7FF). | — | — | — | ✅ | |
reset_defaults |
Reset firmware configuration to factory defaults. | — | — | — | ✅ | |
restore |
Restore configuration from a snapshot file. | path |
applyToFlash=false |
— | ✅ | ✅ |
save_flash |
Persist the current configuration to flash storage. | — | — | — | ✅ | |
set |
Write a configuration value in the selected category. | category, item, value |
— | — | ✅ | ✅ |
shuffle |
Discover PRG/CRT files and run each with optional screen capture. | — | root="/", extensions=["prg","crt"], durationMs=5000, captureScreen=true, maxPrograms=10, outputPath, resetDelayMs=100 |
— | ✅ | |
snapshot |
Snapshot configuration to disk for later restore or diff. | path |
— | — | ✅ | ✅ |
version |
Fetch firmware version details. | — | — | — | ✅ | ✅ |
write_debugreg |
Write a hex value to the Ultimate debug register ($D7FF). | value |
— | — | ✅ |
Grouped entry point for VICE debugger operations (breakpoints, registers, stepping).
| Operation | Description | Required Inputs | Optional Inputs | Notes | C64U | VICE |
|---|---|---|---|---|---|---|
continue_execution |
Exit the Binary Monitor and resume CPU execution (BM 0xAA Exit). | — | — | — | ✅ | |
create_checkpoint |
Create a new checkpoint (breakpoint) in VICE. | address |
endAddress, stopOnHit=true, enabled=true, temporary=false, label, operations, memspace |
— | ✅ | |
delete_checkpoint |
Remove a checkpoint by id. | id |
— | — | ✅ | |
get_checkpoint |
Fetch a single checkpoint by id. | id |
— | — | ✅ | |
get_monitor_state |
Read CPU registers and return the current monitor state. | — | memspace |
— | ✅ | |
get_registers |
Read register values, optionally filtered by name or id. | — | memspace, registers |
— | ✅ | |
list_checkpoints |
List all active VICE checkpoints (breakpoints). | — | — | — | ✅ | |
list_registers |
List available registers (metadata). | — | memspace |
— | ✅ | |
nuclear_reset |
Kill and restart the VICE process (managed instances only). | — | — | — | ✅ | |
set_condition |
Attach a conditional expression to a checkpoint. | id, expression |
— | — | ✅ | |
set_registers |
Write register values. | writes |
memspace |
— | ✅ | |
step |
Single-step CPU execution. | — | count=1, mode |
— | ✅ | |
step_return |
Continue execution until the current routine returns. | — | — | — | ✅ | |
toggle_checkpoint |
Enable or disable a checkpoint by id. | id, enabled |
— | — | ✅ | |
wait_for_state |
Poll CPU registers until PC equals expectedPC or timeout elapses. | — | expectedPC, timeoutMs=5000, pollMs=100 |
— | ✅ |
Grouped entry point for disk mounts, listings, image creation, and program discovery.
| Operation | Description | Required Inputs | Optional Inputs | Notes | C64U | VICE |
|---|---|---|---|---|---|---|
create_image |
Create a blank disk image of the specified format. | format, path |
diskname, tracks |
— | ✅ | |
file_info |
Inspect metadata for a file on the Ultimate filesystem. | path |
— | — | ✅ | |
find_and_run |
Search for a PRG/CRT by name substring and run the first match. | nameContains |
root="/", extensions, caseInsensitive=true, sort="discovered", waitMs=0, captureCandidates=10 |
— | ✅ | |
list_drives |
List Ultimate drive slots and their mounted images. | — | — | — | ✅ | ✅ |
mount |
Mount a disk image with optional verification and retries. | drive, image |
type, attachmentMode, driveMode, verify=false, powerOnIfNeeded=true, resetAfterMount=true, maxRetries=2, retryDelayMs=500 |
supports verify | ✅ | ✅ |
unmount |
Remove the mounted image from an Ultimate drive slot. | drive |
— | — | ✅ | ✅ |
Grouped entry point for drive power, mode, reset, and ROM operations.
| Operation | Description | Required Inputs | Optional Inputs | Notes | C64U | VICE |
|---|---|---|---|---|---|---|
load_rom |
Temporarily load a custom ROM into an Ultimate drive slot. | drive, path |
— | — | ✅ | |
power_off |
Power off a specific Ultimate drive slot. | drive |
— | — | ✅ | ✅ |
power_on |
Power on a specific Ultimate drive slot. | drive |
— | — | ✅ | ✅ |
reset |
Issue an IEC reset for the selected drive slot. | drive |
— | — | ✅ | ✅ |
set_mode |
Set the emulation mode for a drive slot (1541/1571/1581). | drive, mode |
— | — | ✅ | ✅ |
Grouped entry point for sprite/charset extraction, memory dumps, filesystem stats, and firmware health checks.
| Operation | Description | Required Inputs | Optional Inputs | Notes | C64U | VICE |
|---|---|---|---|---|---|---|
charset |
Locate and extract 2KB character sets from RAM. | — | address, scanRange="common", outputPath, pauseDuringRead=true, minNonEmptyChars=32, minEntropy=0.3 |
— | ✅ | |
firmware_health |
Run firmware readiness checks and report status metrics. | — | — | — | ✅ | |
fs_stats |
Walk the filesystem and aggregate counts/bytes by extension. | — | root="/", extensions, includeContainers=true, maxSamplesPerExtension=3 |
— | ✅ | |
memory_dump |
Dump a RAM range to hex or binary files with manifest metadata. | address, length, outputPath |
format="hex", chunkSize=512, pauseDuringRead=true, retries=1 |
— | ✅ | |
sprites |
Scan RAM for sprites and optionally export .spr files. | address, length |
stride=64, maxSprites=16, minNonZeroRows=4, minSetBits=12, includeBase64=true, outputDir, pauseDuringRead=true |
— | ✅ |
Grouped entry point for frame capture and graphics rendering workflows.
| Operation | Description | Required Inputs | Optional Inputs | Notes | C64U | VICE |
|---|---|---|---|---|---|---|
capture_frame |
Capture one or more complete video frames from the active backend. | — | count=1, includePixels=true, encoding="base64" |
— | ✅ | ✅ |
get_display_state |
Read VIC-II and CIA2 registers to determine the current graphics mode and memory layout. Works on C64U and VICE; both backends are read through shared memory primitives so the response shape is identical. | — | — | — | ✅ | ✅ |
render_bitmap |
Import an image file, convert it to VIC-II bitmap memory, write it into RAM, and display it. | imagePath, format |
bitmapAddress=8192, screenAddress=1024, borderColor=0, backgroundColor=0, preserveAspect=true |
— | ✅ | ✅ |
render_petscii_art |
Create PETSCII art from prompts, text, or explicit bitmap data, and optionally display it on the C64. | — | prompt, text, maxWidth, maxHeight, borderColor, backgroundColor, foregroundColor, dryRun=false, bitmap |
— | ✅ | ✅ |
render_petscii_text |
Display PETSCII text with optional border and background colours. | text |
borderColor, backgroundColor |
— | ✅ | ✅ |
render_sprite |
Display supplied 63-byte sprite data at the requested position and colour by writing memory and patching VIC-II registers directly. | sprite |
index=0, x=100, y=100, color=1, multicolour=false |
— | ✅ | ✅ |
Keyboard buffer injection (cross-platform) and joystick simulation (VICE only).
| Operation | Description | Required Inputs | Optional Inputs | Notes | C64U | VICE |
|---|---|---|---|---|---|---|
joystick |
Simulate joystick input by writing directly to CIA1 Port A/B registers. | port, controls, action |
durationMs=80 |
— | ✅ | |
key |
Tap a single key or hold it for a duration. | key |
durationMs=0, count=1 |
— | ✅ | ✅ |
write_text |
Send a text string to the keyboard buffer, with PETSCII token expansion. | text |
delayMs=0 |
— | ✅ | ✅ |
Grouped entry point for memory I/O, screen reads, and screen polling.
| Operation | Description | Required Inputs | Optional Inputs | Notes | C64U | VICE |
|---|---|---|---|---|---|---|
compare_memory |
Compare two memory regions byte-by-byte and report differences. | address1, address2, length |
maxDiffs=10 |
— | ✅ | ✅ |
copy_memory |
Copy a RAM region to another address. | source, dest, length |
— | — | ✅ | ✅ |
disassemble |
Disassemble a memory region into annotated 6502/6510 instructions, including undocumented opcodes with canonical names. Symbol annotations from .vs files are applied when available. Works on both C64U and VICE. |
address |
length=64, instructionCount |
— | ✅ | ✅ |
fill_memory |
Fill a memory range with a repeating byte pattern. | address, length, pattern |
— | — | ✅ | ✅ |
read |
Read a range of bytes and return a hex dump with address metadata. | address |
length=256 |
— | ✅ | ✅ |
read_screen |
Return the current 40x25 text screen converted to ASCII. | — | — | — | ✅ | ✅ |
save_memory |
Dump a memory range to a local file, with an optional PRG load-address header. | startAddress, endAddress, filePath |
asPrg=true |
— | ✅ | ✅ |
search_memory |
Search for a byte pattern within a memory range and return matching addresses. | startAddress, endAddress, pattern |
maxResults=10 |
— | ✅ | ✅ |
wait_for_text |
Poll the screen until a substring or regex appears, or timeout elapses. | pattern |
isRegex=false, caseInsensitive=true, timeoutMs=3000, intervalMs=100 |
— | ✅ | ✅ |
write |
Write a hexadecimal byte sequence into RAM. | address, bytes |
verify=false, expected, mask, abortOnMismatch=true |
supports verify | ✅ | ✅ |
Grouped entry point for Commodore and Epson printing helpers.
| Operation | Description | Required Inputs | Optional Inputs | Notes | C64U | VICE |
|---|---|---|---|---|---|---|
define_chars |
Define custom printer characters (Commodore DLL mode). | firstChar, chars |
secondaryAddress |
— | ✅ | |
print_bitmap |
Print a bitmap row via Commodore (BIM) or Epson ESC/P workflows. | printer="commodore", columns |
repeats, useSubRepeat, secondaryAddress, ensureMsb=true, mode, density, timesPerLine |
— | ✅ | |
print_text |
Generate BASIC that prints text to device 4. | text |
target="commodore", secondaryAddress, formFeed=false |
— | ✅ |
Grouped entry point for program upload, execution, and batch workflows.
| Operation | Description | Required Inputs | Optional Inputs | Notes | C64U | VICE |
|---|---|---|---|---|---|---|
batch_run |
Run multiple PRG/CRT programs with post-run assertions. | programs |
continueOnError=false, durationMs=2000, outputPath, resetDelayMs=100 |
— | ✅ | ✅ |
bundle_run |
Capture screen, memory, and debug registers into an artifact bundle. | runId, outputPath |
captureScreen=true, memoryRanges, captureDebugReg=true |
— | ✅ | |
cross_platform_greeting |
Show a platform-customized greeting on one or more configured backends, capture screenshots, and verify the results. | — | platforms=["vice","c64u"], messageTemplate="HAVE A GREAT DAY, {PLATFORM}!", verify=true, captureScreenshot=true, outputPath, restoreActiveBackend=true, timeoutMs=1500, pollIntervalMs=100 |
supports verify | ✅ | ✅ |
load_prg |
Load a PRG from Ultimate storage without executing it. | path |
symbolsFile |
— | ✅ | |
run_crt |
Mount and run a CRT cartridge image. | path |
— | — | ✅ | |
run_prg |
Load and execute a PRG from Ultimate-visible storage on c64u or a host-local path on VICE. | path |
symbolsFile |
— | ✅ | ✅ |
upload_run_asm |
Assemble 6502/6510 source, upload the PRG, and execute it. | program |
verify=false |
supports verify | ✅ | ✅ |
upload_run_basic |
Upload Commodore BASIC v2 source and execute it immediately. | program |
verify=false |
supports verify | ✅ | ✅ |
Grouped entry point for BASIC and assembly RAG lookups.
| Operation | Description | Required Inputs | Optional Inputs | Notes | C64U | VICE |
|---|---|---|---|---|---|---|
asm |
Retrieve 6502/6510 assembly references from the local knowledge base. | q |
k=3 |
— | ✅ | ✅ |
basic |
Retrieve BASIC references and snippets from the local knowledge base. | q |
k=3 |
— | ✅ | ✅ |
Switch the active backend between C64U hardware and the VICE emulator at runtime.
| Operation | Description | Required Inputs | Optional Inputs | Notes | C64U | VICE |
|---|---|---|---|---|---|---|
select |
Switch the active runtime backend without restarting the MCP server. | backend |
— | — | ✅ | ✅ |
Grouped entry point for SID control, playback, composition, and analysis workflows.
| Operation | Description | Required Inputs | Optional Inputs | Notes | C64U | VICE |
|---|---|---|---|---|---|---|
analyze |
Automatically analyze SID playback when verification is requested. | request |
durationSeconds, expectedSidwave |
— | ✅ | |
capture_samples |
Capture raw stereo PCM samples from the C64 Ultimate audio UDP stream. | — | count=256, encoding="base64" |
— | ✅ | |
compile_play |
Compile SIDWAVE or CPG source and optionally play it immediately. | — | sidwave, cpg, format, output="prg", dryRun=false |
— | ✅ | ✅ |
generate |
Generate a lightweight SID arpeggio playback sequence. | — | root="C4", pattern="0,4,7", steps=16, tempoMs=120, waveform="tri", preset="classic" |
— | ✅ | ✅ |
note_off |
Release a SID voice by clearing its gate bit. | voice |
— | — | ✅ | ✅ |
note_on |
Trigger a SID voice with configurable waveform, ADSR, and pitch. | — | voice=1, note, frequencyHz, system="PAL", waveform="pulse", pulseWidth=2048, attack=1, decay=1, sustain=15, release=3 |
— | ✅ | ✅ |
pipeline |
Compile a SIDWAVE score, play it, and analyze the recording. | — | sidwave, cpg, output="prg", waitBeforeCaptureMs=500, analysisDurationSeconds=3, expectedSidwave, verifySilenceBefore=true, verifySilenceAfter=true, silenceDurationSeconds=1.5, silenceRmsThreshold=0.02, postSilenceWaitMs=200, silenceWaitMs=150 |
supports verify | ✅ | |
play_mod_file |
Play a MOD tracker module via the Ultimate SID player. | path |
— | — | ✅ | |
play_preset |
Compile and play a built-in SID preset such as Für Elise by Beethoven. | — | preset="fuer_elise", platforms, verify=true, analysisDurationSeconds=4, waitBeforeCaptureMs=400, restoreActiveBackend=true |
supports verify | ✅ | ✅ |
play_sid_file |
Play a SID file stored on the Ultimate filesystem. | path |
songnr |
— | ✅ | |
record_analyze |
Record audio for a fixed duration and return SID analysis metrics. | durationSeconds |
expectedSidwave |
— | ✅ | |
reset |
Soft or hard reset of SID registers to clear glitches. | — | hard=false |
— | ✅ | ✅ |
set_volume |
Set the SID master volume register at $D418 (0-15). | volume |
— | — | ✅ | ✅ |
silence_all |
Silence all SID voices with optional audio verification. | — | verify=false |
supports verify | ✅ | ✅ |
Grouped entry point for starting and stopping Ultimate streaming sessions.
| Operation | Description | Required Inputs | Optional Inputs | Notes | C64U | VICE |
|---|---|---|---|---|---|---|
start |
Start an Ultimate streaming session toward a host:port target. | stream, target |
— | — | ✅ | |
stop |
Stop an active Ultimate streaming session. | stream |
— | — | ✅ |
Grouped entry point for power, reset, menu, and background task control.
| Operation | Description | Required Inputs | Optional Inputs | Notes | C64U | VICE |
|---|---|---|---|---|---|---|
list_tasks |
List known background tasks with status metadata. | — | — | — | ✅ | ✅ |
menu |
Toggle the Ultimate menu button for navigation. | — | — | — | ✅ | |
pause |
Pause the machine until resumed. | — | — | — | ✅ | |
performance_report |
Summarize diagnostics spans and tool latencies from the current or latest MCP session. | — | scope="current", includeTimeline=true, maxEntries=25 |
— | ✅ | ✅ |
poweroff |
Request a controlled shutdown via the Ultimate firmware. | — | — | — | ✅ | ✅ |
reboot |
Trigger a firmware reboot to recover from faults. | — | — | — | ✅ | ✅ |
reset |
Issue a soft reset without cutting power. | — | — | — | ✅ | ✅ |
resume |
Resume CPU execution after a pause. | — | — | — | ✅ | |
start_task |
Start a named background task that runs on an interval. | name, operation |
arguments={}, intervalMs=1000, maxIterations |
— | ✅ | ✅ |
stop_all_tasks |
Stop every running background task and persist state. | — | — | — | ✅ | ✅ |
stop_task |
Stop a specific background task and clear its timer. | name |
— | — | ✅ | ✅ |
Grouped entry point for reading and updating selected VICE resources.
| Operation | Description | Required Inputs | Optional Inputs | Notes | C64U | VICE |
|---|---|---|---|---|---|---|
resource_get |
Read a VICE configuration resource (safe prefixes only). | name |
— | — | ✅ | |
resource_set |
Write a VICE configuration resource (safe prefixes only). | name, value |
— | — | ✅ |
| Name | Summary |
|---|---|
c64://guide/index |
Explains how to approach each knowledge bundle and when to consult it. |
c64://guide/bootstrap |
Step-by-step rules for safe automation, verification, and rollback on the C64. |
c64://guide/fast-paths |
Condensed routing guide for one-call demos, backend switching, and when to prefer orchestration over manual tool composition. |
c64://vice/binary-monitor-spec |
Transport framing, single-client constraints, command semantics, and monitor side effects that shape all VICE-backed operations. |
c64://basic/spec |
Token definitions, syntax rules, and device I/O guidance for BASIC v2. |
c64://basic/pitfalls |
Quickref covering quotation handling, line length, tokenization, variable names, and other BASIC traps. |
c64://assembly/6510-spec |
Official opcode matrix, addressing modes, and zero-page strategy for the 6510 CPU. |
c64://sound/sid/spec |
Register map, waveform behaviour, and ADSR envelopes for expressive SID playback. |
c64://sound/sidwave/spec |
Defines the SIDWAVE interchange format used by the SID composer workflow. |
c64://sound/sid/file-format |
Explains PSID/RSID headers, metadata blocks, and compatibility notes for imported music. |
c64://sound/sid/best-practices |
Captures proven waveforms, ADSR presets, phrasing, and verification workflow for pleasant SID music. |
c64://graphics/vic/spec |
Covers raster timing, sprite control, colour RAM, and bitmap modes on the VIC-II. |
c64://graphics/character-set |
Character code table mapping PETSCII codes to screen codes, glyphs, and keyboard input. |
c64://graphics/petscii/style-guide |
Documents colour palette, readability presets, dithering patterns, and best practices for creating artistic and readable PETSCII displays. |
c64://graphics/sprite-charset/best-practices |
Documents sprite and charset workflows, memory layout, VIC-II configuration, common pitfalls, and proven techniques for hardware-accelerated graphics. |
c64://memory/map |
Page-by-page breakdown of the 64 KB address space with hardware, ROM, and RAM regions. |
c64://memory/zero-page-and-workspace |
Documents zero-page variables, BASIC pointers, and KERNAL workspace addresses. |
c64://kernal/rom-routines |
Lists KERNAL ROM vectors and service routines for OS-level functionality. |
c64://io/spec |
Covers VIC-II, SID, CIA, and system control registers with address ranges and usage notes. |
c64://io/cia/spec |
Details CIA 1/2 registers, timers, interrupts, and keyboard matrix layout. |
c64://printer/spec |
Covers device setup, control codes, and Ultimate 64 integration for printers. |
c64://printer/commodore/text |
Character sets, control codes, and formatting for Commodore MPS text output. |
c64://printer/commodore/bitmap |
Details bitmap modes, graphics commands, and data layout for MPS bitmap printing. |
c64://printer/epson/text |
Lists ESC/P control codes and formatting advice for Epson FX text output. |
c64://printer/epson/bitmap |
Explains bit-image modes, density options, and data packing for Epson bitmap jobs. |
c64://printer/prompt-guide |
Reusable prompt templates that drive complex printer jobs through the MCP server. |
| Name | Description |
|---|---|
assembly-program |
Route 6502/6510 routine requests to the canonical assembly skill. |
basic-program |
Route bespoke Commodore BASIC v2 requests to the canonical BASIC skill. |
cross-platform-demo |
Route quick visible demo requests to the cross-platform demo skill. |
drive-manager |
Route disk-image and drive-state requests to the canonical drive skill. |
graphics-demo |
Route graphics requests to the canonical graphics skill. |
hello-world |
Route ultra-fast hello-world and smoke-test requests to the canonical greeting skill. |
memory-debug |
Route reversible memory inspection or patching work to the canonical memory skill. |
preset-music-demo |
Route quick recognizable tune requests to the SID music skill. |
printer-job |
Route printer work to the canonical printer skill. |
sid-music |
Route SID playback and composition work to the canonical SID skill. |
Please log in to share your review and rating for this MCP.
Explore related MCPs that share similar capabilities and solve comparable challenges
by modelcontextprotocol
A Model Context Protocol server for Git repository interaction and automation.
by zed-industries
A high‑performance, multiplayer code editor designed for speed and collaboration.
by modelcontextprotocol
Model Context Protocol Servers
by modelcontextprotocol
A Model Context Protocol server that provides time and timezone conversion capabilities.
by cline
An autonomous coding assistant that can create and edit files, execute terminal commands, and interact with a browser directly from your IDE, operating step‑by‑step with explicit user permission.
by upstash
Provides up-to-date, version‑specific library documentation and code examples directly inside LLM prompts, eliminating outdated information and hallucinated APIs.
by daytonaio
Provides a secure, elastic infrastructure that creates isolated sandboxes for running AI‑generated code with sub‑90 ms startup, unlimited persistence, and OCI/Docker compatibility.
by continuedev
Enables faster shipping of code by integrating continuous AI agents across IDEs, terminals, and CI pipelines, offering chat, edit, autocomplete, and customizable agent workflows.
by github
Connects AI tools directly to GitHub, enabling natural‑language interactions for repository browsing, issue and pull‑request management, CI/CD monitoring, code‑security analysis, and team collaboration.
{
"mcpServers": {
"c64bridge": {
"command": "npx",
"args": [
"-y",
"c64bridge"
],
"env": {}
}
}
}claude mcp add c64bridge npx -y c64bridge