C64 Bridge

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 firm