C64bridge MCP Server

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

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: VICE
    • 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
  • Example Workflow
  • HTTP Invocation
  • Build and Test
  • Documentation
  • Static MCP Interface
  • MCP API Reference
    • Tools
      • c64_config
      • c64_debug
      • c64_disk
      • c64_drive
      • c64_extract
      • c64_graphics
      • 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 C64 Ultimate hardware, VICE, or both.
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 hardware c64u and emulator 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 C64 Ultimate, VICE, or both.
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:

• only C64 Ultimate hardware
• only VICE
• both backends in one session, with runtime switching

The detailed lookup order, merge rules, backend examples, and override model are in the Configuration section below.

4. Connect from an MCP Client

If you use VS Code, follow the VS Code MCP Setup section below.

If you use another MCP client, point it at the stdio server entry point and pass any required environment variables exactly as documented in this README and in mcp.json.

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 a c64u section supplies the C64 Ultimate configuration.
• The first file that contains a vice section supplies the VICE configuration.
• This allows a project-local .c64bridge.json to define c64u while ~/.c64bridge.json defines vice, with both backends available at runtime.

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.

Backend Configuration: VICE

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.
• If no explicit binary is configured, the runtime prefers /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.

Runtime Backend Switching

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 vice
• c64_select_backend switches backends without restarting the MCP server
• c64://platform/status reports the active backend and the full configured backend set
• In prompts, say things like use vice, vice: run this program, use c64u, or run this on the real machine
• In VS Code, include the backend preference in the same prompt when you want to force emulator versus hardware execution

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

VS Code MCP Setup

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 or vice
• LOG_LEVEL=debug enables verbose logging

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

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

VICE Runtime

VICE Audio Capture

SID Playback

RAG

Testing

Example Workflow

Compose a children’s song with ChatGPT and VS Code:

Then render PETSCII art for it:

This is representative of the intended workflow:

1. Ask the MCP client to generate or refine C64-oriented content.
2. Use grouped tools such as c64_program, c64_graphics, and c64_sound to execute it.
3. 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.
• The following curl commands are illustrative so you can see what grouped MCP calls look like over HTTP.

# 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

Build and Test

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. Use npm start (from source) or npx -y c64bridge@latest (published package) as shown in the Quick Start section above.

Documentation

• doc/developer.md — development workflow and RAG details
• data/context/bootstrap.md — primer injected ahead of prompts
• doc/c64u/c64-openapi.yaml — REST surface (OpenAPI 3.1)
• AGENTS.md — LLM-facing quick setup, usage, and personas

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 15 tools, 26 resources, and 10 prompts for controlling your Commodore 64.

Tools

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_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 and assembly RAG lookups.

c64_select_backend

Switch the active backend between C64U hardware and the VICE emulator at runtime.

c64_sound

Grouped entry point for SID control, playback, composition, and analysis workflows.

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

Grouped entry point for reading and updating selected VICE resources.

Resources

Prompts

Documentation truncated — see the full README on GitHub.