C64 Bridge Community

Frequently asked questions

What does the C64 Bridge MCP server do?

C64 Bridge 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 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. 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 C64 Bridge Contents Overview Features Quick Start 1. Install Node.js 24+ and npm 2. Start the Server 3. Add Backend Configuration 4. Connect from an MCP Client Configuration Configuration File Order Configuration Merge Rules Backend Configuration: C64 Ultimate Backend Configuration: U2-family Backend Configuration: VICE VICE Window Modes Recommended VICE Configurations Runtime Backend Switching VS Code MCP Setup Enable the C64 Agent Optional Overrides Environment Variables in MCP Client Configs Runtime Environment Variable Reference Server Runtime C64 Ultimate VICE Runtime VICE Audio Capture SID Playback RAG Testing Claude Code Example Workflow HTTP Invocation Build and Test Documentation Static MCP Interface MCP API Reference Tools c64\ batch c64\ config c64\ debug c64\ disk c64\ drive c64\ extract c64\ graphics c64\ input c64\ memory c64\ printer c64\ program c64\ rag c64\ select\ backend c64\ sound c64\ stream c64\ system c64\ vice Resources Prompts 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. Install Node.js 24+ and npm Linux (Ubuntu or Debian): Recommended: Fallback: macOS: Windows: Verify the installation: Expected result: v24.x 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. 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. 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: Mode Configuration What happens Use when --- --- --- --- Visible VICE VISIBLE=true VICE opens a normal desktop window. Warp defaults to off. You are developing locally and want to watch or interact with the emulator. Minimized VICE VISIBLE=true , VICE ARGS="-minimized" VICE still runs as a normal desktop app, but its window starts iconified. Binary Monitor operations, screen reads, frame capture, and keyboard input continue to work. You are using an agent locally and do not want the emulator stealing focus, but still want the option to restore the window. Headless/Xvfb VICE VISIBLE=false C64 Bridge launches VICE without a user-facing desktop window, using Xvfb unless disabled. Warp defaults to on. CI, unattended tests, servers, or any session where no one needs to inspect the emulator window. 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 . Profile Targets Key limits --- --- --- c64u C64 Ultimate, Ultimate 64 Full Ultimate REST surface, including machine input and streaming. u2 U2, U2+, U2+L Shared REST subset; no machine input, debug registers, power-off, or streaming. vice VICE emulator Binary Monitor-backed emulator controls; no Ultimate REST API. 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. Backend Screenshot --- --- C64 Ultimate U2-family Frame capture unavailable (no firmware streaming). VICE 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: 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. Optional Overri

How do I install C64 Bridge?

Run the install command shown above, then paste the config for your client (Claude Desktop, Claude Code, Cursor, VS Code or Windsurf) into its MCP settings and restart the client.

Is C64 Bridge free to use?

The MCP server itself is free to install. The source is public on https://github.com/chrisgleissner/c64bridge. Any third-party service it calls may require its own API key and account.

Which clients support C64 Bridge?

Any MCP-compatible client can use it, including Claude Desktop, Claude Code, Cursor, VS Code, Windsurf and custom agents.