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:

1. Start the MCP server.
2. Point it at C64U/U64 hardware, a U2-family cartridge, VICE, or any configured combination.
3. Let the client call grouped MCP tools such as c64_program, c64_memory, c64_graphics, and c64_sound.
4. 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:

1. Install Node.js 24+ and npm.
2. Start the server.
3. Add backend configuration for C64U/U64, U2-family, VICE, or any combination.
4. Connect from VS Code or another MCP client.

1. Install Node.js 24+ and npm

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

2. Start the Server

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.

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:

1. C64BRIDGE_CONFIG, if it points to a config file
2. .c64bridge.json in the project root
3. ~/.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:

{
  "c64u": {
    "host": "c64u",
    "port": 80,
    "networkPassword": "secret"
  }
}

• 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:

{
  "u2": {
    "host": "u2",
    "port": 80,
    "networkPassword": "secret"
  }
}

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:

{
  "vice": {
    "exe": "/usr/bin/x64sc",
    "directory": "/usr/local/share/vice"
  }
}

• 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:

{
  "servers": {
    "c64bridge": {
      "command": "npx",
      "args": ["-y", "c64bridge@latest"],
      "env": {
        "C64_MODE": "vice",
        "VICE_VISIBLE": "true",
        "VICE_ARGS": "-minimized",
        "VICE_WARP": "false"
      }
    }
  }
}

Headless automation, VICE runs without a visible desktop window:

{
  "servers": {
    "c64bridge": {
      "command": "npx",
      "args": ["-y", "c64bridge@latest"],
      "env": {
        "C64_MODE": "vice",
        "VICE_VISIBLE": "false",
        "VICE_WARP": "true"
      }
    }
  }
}

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):

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 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:

{
  "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.

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 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:

{
  "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 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.
• 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:

1. the explicit environment variable from your MCP client config or shell
2. the merged JSON config section loaded from C64BRIDGE_CONFIG, the repo .c64bridge.json, then ~/.c64bridge.json
3. the built-in default compiled into the server

When an environment variable has no JSON config equivalent, the order is:

1. the explicit environment variable from your MCP client config or shell
2. 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:

{
  "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_ARGS": "-minimized",
        "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"
      }
    }
  }
}

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