C64 Bridge
[Logo]
Your AI Command Bridge for the Commodore 64.
[npm]
[Build]
[codecov]
[License: GPL v2]
[Platform]
[Install in VS Code]
[Install in VS Code Insiders]
[Install in Visual Studio]
[Install in Cursor]
[Use with Claude Code]
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 C64 Ultimate, Ultimate 64, or U2-family cartridge. You can also switch to a VICE emulator session, so one MCP conversation can span hardware and emulation.
Built-in resources, skills, and RAG give your AI coding agent a head start with classic C64 programming and modern Ultimate features, including REU, CPU turbo, 10 SIDs, LED control, UCI networking, and UPIC full-colour border graphics.
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.
Contents
Overview
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:
- Start the MCP server.
- Point it at C64U/U64 hardware, a U2-family cartridge, VICE, or any configured combination.
- Let the client call grouped MCP tools such as
c64_program, c64_memory, c64_graphics, and c64_sound.
- Switch backends at runtime with
c64_select_backend when both are configured.
Features
- Program runners for BASIC, 6510 assembly, and PRG or CRT execution
- Full memory access, including raw reads and writes plus screen polling
- System integration for drives, files, printers, and task orchestration
- SID music tools for playback, composition, generation, and verification
- Built-in knowledge resources and prompts for safer LLM workflows
- Mixed runtime support for
c64u (C64U/U64), u2 (U2/U2+/U2+L), and vice
Quick Start
If you want the shortest path, do these four things:
- Install Node.js 24+ and npm.
- Start the server.
- Add backend configuration for C64U/U64, U2-family, VICE, or any combination.
- Connect from VS Code or another MCP client.
1. Install Node.js 24+ and npm
Linux (Ubuntu or Debian):
Recommended:
Fallback:
macOS:
Windows:
Verify the installation:
Expected result: v24.x
2. Start the Server
Use one of the following entry points.
Run from npx with zero setup:
Run from a local npm install:
Run from source for development or testing:
On startup, the server probes the selected target, performs connectivity checks, and then announces that it is running on stdio.
3. Add Backend Configuration
The server can run against one or more of:
- C64U/U64 hardware (
c64u)
- U2, U2+, or U2+L (
u2)
- VICE (
vice)
The detailed lookup order, merge rules, backend examples, and override model are in the Configuration section below.
4. Connect from an MCP Client
C64 Bridge ships a single canonical stdio entry point that every MCP client uses:
- VS Code (GitHub Copilot) — see VS Code MCP Setup.
- Claude Code (CLI and VS Code plugin) — see Claude Code.
- Cursor, Visual Studio, VS Code Insiders — use the install badges at the top of this README.
- Any other MCP client — point it at the same
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. Select c64u, u2, or vice in the shared Configuration; clients only need the command.
Configuration
Configuration File Order
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 directory
Configuration Merge Rules
Configuration is merged per backend section while scanning those files in order.
- The first file that contains each backend section (
c64u, u2, or vice) supplies that backend's configuration.
- This allows a project-local
.c64bridge.json to define c64u while ~/.c64bridge.json defines u2 or vice.
Backend Configuration: C64 Ultimate
Use this for a C64 Ultimate or Ultimate 64:
- If no file is found, the default target is
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.
Firmware Requirements for Native Input and Menu Screens
The following operations require recently added Ultimate REST endpoints. C64 Bridge detects or explains unavailable endpoints without exposing a raw firmware error.
Before choosing an endpoint-dependent operation, read c64://platform/status. It probes machine:input safely and reports whether it is available. When native input is unavailable, use key or write_text for ordinary C64 input instead of physical matrix events. machine:menu_screen can only be confirmed after an Ultimate menu is visible; its tool returns fallback guidance rather than a transport error when no matrix can be read.
c64_input keyboard, release_all, and state, plus hardware joystick, use machine:input. They require a C64U firmware version that provides this endpoint, or U64 firmware 3.15 or later. machine:input is not available on U2-family cartridges.
c64_system read_menu_screen uses machine:menu_screen; it requires a C64U firmware version that provides this endpoint, or U64/U2 firmware 3.15 or later.
- On C64U/U64,
c64_system power_cycle verifies Tool Menu navigation with machine:menu_screen, so it has the same firmware requirement. U2-family power_cycle uses REST reboot instead.
Backend Configuration: U2-family
Use this profile for U2, U2+, and U2+L cartridges:
Set C64_MODE=u2 to make this the initial backend. U2_HOST, U2_PORT, and U2_PASSWORD override this profile. U2-family firmware exposes the shared REST subset; it does not provide machine input, debug-register access, power-off, or streaming. read_menu_screen requires U2 firmware 3.15 or later.
Backend Configuration: VICE
C64 Bridge can either connect to an already running VICE Binary Monitor or manage a local VICE process for you. The usual managed setup only needs the emulator binary and, when auto-detection cannot find it, the VICE resource directory:
exe is optional when x64sc or x64 is on PATH. If no explicit binary is configured, the runtime prefers /usr/local/bin/x64sc when present, then falls back to x64sc or x64 on PATH.
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.
host and port are optional and default to 127.0.0.1:6502, the Binary Monitor endpoint C64 Bridge starts for managed local sessions. On local endpoints, C64 Bridge first tries to reuse an already running monitor before starting its own process.
visible, warp, and args are optional runtime controls. They can live in JSON config, but most users set their environment-variable equivalents from the MCP client because they are per-session preferences.
- By default, VICE is started lazily on first access. When setting the environment variable
VICE_PREWARM=1, C64 Bridge starts or connects VICE in the background during MCP startup.
VICE_BINARY, VICE_DIRECTORY, VICE_HOST, VICE_PORT, VICE_VISIBLE, VICE_WARP, VICE_ARGS, and VICE_PREWARM override the JSON values without editing config files.
VICE Window Modes
Choose the window mode based on where the MCP server runs:
Minimized and headless are not the same thing. Minimized is still a visible desktop session with a real VICE window; it is simply hidden by the window manager at startup. Headless/Xvfb has no user-facing window, so it is better for automation but less convenient when you need to debug by looking at the emulator.
For normal local MCP use, prefer minimized VICE. It avoids focus stealing while preserving the ability to restore the window for visual inspection. Prefer headless/Xvfb for CI and remote or display-less environments.
FORCE_XVFB=1 forces the Xvfb path even if a graphical session is available. DISABLE_XVFB=1 disables that fallback and uses the current display, which is mainly useful for troubleshooting display detection.
Recommended VICE Configurations
Local agent session, VICE starts minimized:
Headless automation, VICE runs without a visible desktop window:
If VICE is installed outside the usual search paths, add VICE_BINARY and, if ROM/resource auto-detection fails, VICE_DIRECTORY to either example.
[!NOTE]
VICE supports only the operations marked with a VICE checkmark in the MCP API Reference. Unsupported operations return unsupported_platform.
Runtime Backend Switching
Configure any combination of c64u, u2, and vice. C64 Bridge starts on C64_MODE (default c64u) and keeps every configured backend ready for c64_select_backend.
Use c64://platform/status to inspect the active backend and available tools. State the target in the same prompt, for example u2: list drives, c64u: run this PRG, or vice: write HELLO. On U2-family cartridges, c64_system power_cycle uses REST reboot; C64U/U64 uses verified Tool Menu navigation, and VICE starts fresh.
Prompt illustration (issued via Copilot in VS Code, using GPT 5.4 Medium):
The screenshots below are available for the two backends that provide frame capture. C64U uses streamed video frames; VICE captures and normalizes its display. U2-family cartridges do not provide firmware streaming, so they intentionally have no screenshot row.
Host File Access
Tool arguments that name a file or directory on the machine running C64 Bridge (memory dumps, configuration snapshots, sprite and charset exports, run artifacts, symbol files, and VICE PRG or disk image paths) are confined to a set of allowed directories:
- the working directory of the server, unless it is the user's home directory or
/
~/.c64bridge
- the system temporary directory (
os.tmpdir())
Paths are resolved to their real location before the check, so .. segments and symbolic links cannot leave these directories. A rejected path produces a validation error that lists the allowed directories, and nothing is written. Files read through these arguments are limited to 16 MiB (64 MiB for disk images).
Set C64BRIDGE_ALLOWED_DIRS to add directories. Separate entries with the platform path delimiter (: on Linux and macOS, ; on Windows). The single value * disables the confinement.
Earlier versions accepted any path. Clients that pass paths outside these directories must now add them through C64BRIDGE_ALLOWED_DIRS.
Access Mode
Every operation has an effect: read (no change), write (changes machine or emulator state that a reset undoes, or writes a host file) or destructive (survives a reset or interrupts availability, for example power off, power cycle, reboot, flash save, load or reset to defaults, drive ROM load, disk image creation, debug register write, and config restore with applyToFlash). tools/list publishes MCP annotations derived from these effects, and each operation line in a tool description names its effect when it is not read.
Set C64BRIDGE_ACCESS to restrict what a client may call:
full (default): all operations are allowed.
no-destructive: destructive operations are rejected.
read-only: only read operations are allowed.
The variable is read on every call. An unknown value is treated as read-only and logged to stderr once. A rejected call returns a validation error that names the operation, its effect and the active mode. c64_batch checks each command separately, and c64_system start_task checks the effect of its task operation when the task starts. c64://platform/status shows the active mode.
After c64_system poweroff on C64U/U64, power must be restored at the outlet. The machine starts by itself only if automatic startup on power restoration is enabled in its configuration.
Operator Environment Variables
These variables are read by the server itself and are set in the env block of the MCP client configuration. C64BRIDGE_ALLOWED_DIRS and C64BRIDGE_ACCESS are described above.
VS Code MCP Setup
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:
Then click the start button shown above the c64bridge entry.
Your MCP server should now be running:
[VS Code Started MCP server]
For more details, see the official VS Code MCP Server documentation.
Enable the C64 Agent
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.
[VS Code C64 agent]
Optional Overrides
You can add env entries in .vscode/mcp.json to select a config file, override C64 Ultimate connection details, or force an initial backend:
C64BRIDGE_CONFIG points to a specific config file
C64U_HOST, C64U_PORT, and C64U_PASSWORD override the C64 Ultimate connection without editing config files
C64_MODE forces the initial backend to c64u, u2, or vice; U2_HOST, U2_PORT, and U2_PASSWORD override the selected U2 profile. C64U_* variables apply to the U2 profile only when the configuration has no u2 section.
LOG_LEVEL=debug enables verbose logging
For VICE-specific overrides such as VICE_ARGS=-minimized, VICE_VISIBLE=false, or custom VICE paths, use the patterns in Backend Configuration: VICE.
Environment Variables in MCP Client Configs
Every 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:
- the explicit environment variable from your MCP client config or shell
- the merged JSON config section loaded from
C64BRIDGE_CONFIG, the repo .c64bridge.json, then ~/.c64bridge.json
- the built-in default compiled into the server
When an environment variable has no JSON config equivalent, the order is:
- the explicit environment variable from your MCP client config or shell
- the built-in default
That rule applies uniformly across the documented runtime environment variables below.
Example: start on minimized VICE with a specific ROM or resource directory, plus a hardware fallback that can still be selected instantly at runtime:
Example: keep JSON config files for backend endpoints, but override diagnostics, polling, and RAG behavior from VS Code:
Runtime Environment Variable Reference
Every runtime environment variable documented in mcp.json can be set in your MCP client configuration, including .vscode/mcp.json under servers.c64bridge.env.
Server Runtime
C64 Ultimate
U2-family
VICE Runtime
VICE Audio Capture
SID Playback
RAG
Testing
Claude Code
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:
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, u2, or 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.
Claude Desktop and Cursor
Both clients use the same mcpServers shape (checked against the official MCP quickstart for Claude Desktop and the Cursor MCP documentation):
- Claude Desktop: Settings, Developer, Edit Config opens
claude_desktop_config.json (macOS ~/Library/Application Support/Claude/claude_desktop_config.json, Windows %APPDATA%\Claude\claude_desktop_config.json). Restart Claude Desktop completely after saving. Claude Desktop starts the server with its own PATH; if npx is not found or is too old, use the absolute path of a Node 24 npx as command.
- Cursor:
.cursor/mcp.json in a project, or ~/.cursor/mcp.json for all projects.
- Replace
192.168.1.99 with the IP address of your Ultimate (the default host name c64u only works when it resolves on your network). For VICE use "C64_MODE": "vice" instead.
- The server writes its log to stderr and then waits for the client on stdin. Started by hand in a terminal it appears to hang; that is expected, stop it with Ctrl-C.
- Claude Code sets the same variable with
-e (--env), placed before the -- that starts the server command: claude mcp add c64bridge -e C64U_HOST=192.168.1.99 -- npx -y c64bridge@latest.
Example Workflow
Compose a children’s song with ChatGPT and VS Code:
[duck song]
Then render PETSCII art for it:
[duck petscii]
This is representative of the intended workflow:
- Ask the MCP client to generate or refine C64-oriented content.
- Use grouped tools such as
c64_program, c64_graphics, and c64_sound to execute it.
- Verify the result via screen reads, frame capture, memory inspection, or audio analysis.
HTTP Invocation
- Preferred transport is
stdio.
- The HTTP bridge is disabled by default and is intended only for manual testing. Start it with
npx -y c64bridge@latest --http 3000 (from a checkout: npm start -- --http 3000). The port defaults to 3000; the server binds to 127.0.0.1 only. Set C64BRIDGE_HTTP_TOKEN and send Authorization: Bearer <token> to require a token.
- The single endpoint is
http://127.0.0.1:<port>/mcp and speaks MCP JSON-RPC. Every request needs Content-Type: application/json and Accept: application/json, text/event-stream; the answer arrives as one server-sent event (data: {...}).
- There are no per-tool REST routes. A grouped tool is called with
tools/call, and op goes inside arguments.
Build and Test
The ./build script at the project root wraps all development tasks behind a single, self-documented interface:
Starting the MCP server is not managed by ./build. Use npm start (from source) or npx -y c64bridge@latest (published package) as shown in the Quick Start section above.
Documentation
Static MCP Interface
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.
MCP API Reference
This MCP server exposes 17 tools, 53 resources, and 11 prompts for controlling your Commodore 64.
See the hardening behavior guide for host path restrictions, argument limits, task retention, cancellation and verification semantics.
Tools
Address range convention: address + length means start address plus byte count; startAddress + endAddress means inclusive bounds.
c64_batch
Execute multiple c64bridge tool calls in a single request. Reduces latency for multi-step workflows.
No operations defined.
c64_config
Grouped entry point for configuration reads/writes, diagnostics, and snapshots.
c64_debug
Grouped entry point for VICE debugger operations (breakpoints, registers, stepping).
c64_disk
Grouped entry point for disk mounts, listings, image creation, and program discovery.
c64_drive
Grouped entry point for drive power, mode, reset, and ROM operations.
c64_extract
Grouped entry point for sprite/charset extraction, memory dumps, filesystem stats, and firmware health checks.
c64_graphics
Grouped entry point for frame capture and graphics rendering workflows.
c64_input
Cross-platform PETSCII typing plus native Ultimate keyboard and joystick events.
c64_memory
Grouped entry point for memory I/O, screen reads, and screen polling.
c64_printer
Grouped entry point for Commodore and Epson printing helpers.
c64_program
Grouped entry point for program upload, execution, and batch workflows.
c64_rag
Grouped entry point for BASIC, assembly and curated-docs RAG lookups.
c64_select_backend
Switch the active backend between C64U/U64 hardware, U2-family cartridges, and the VICE emulator at runtime.
c64_sound
SID control, playback, composition and audio analysis.
c64_stream
Grouped entry point for starting and stopping Ultimate streaming sessions.
c64_system
Grouped entry point for power, reset, menu, and background task control.
c64_vice
VICE resources, snapshots.
Resources
Prompts