c64bridge

MCP server to control and program the Commodore 64 Ultimate and Ultimate 64 via REST API

Installation

Run this command in your terminal to add the MCP server to Claude Code.

Run in terminal:

Command

claude mcp add --transport stdio chrisgleissner-c64bridge node ./node_modules/c64bridge/dist/index.js \
  --env LOG_LEVEL="debug" \
  --env C64BRIDGE_CONFIG="Path to MCP configuration (absolute) or rely on defaults"

How to use

C64 Bridge is an MCP server that drives a real Commodore 64 via REST APIs exposed by the Ultimate 64 hardware (and, experimentally, a VICE runner). It supports both stdio (local AI integration) and HTTP (remote tooling) transports and provides a suite of tools to interact with the C64 hardware, memory, drives, files, printers, and SID audio. You can use the stdio path for seamless local AI workflows, or enable the HTTP bridge for remote tool invocations. The server exposes a rich MCP API with 12 tools and 25 resources, enabling tasks such as program execution, memory reads/writes, screen capture, and system operations, all orchestrated from prompts or automation scripts.

To run it, start the server via Node.js (as shown in the Quick Start). Once running, you can send MCP requests to control the C64, upload and run BASIC programs or PRG/CRT images, read the screen, reset the machine, and manage hardware components like drives and printers. If you’re integrating with IDEs or editors, use the explicit MCP server configuration and, for tooling like GitHub Copilot Chat, declare the server in your editor’s MCP settings so prompts can orchestrate the C64 from within your development environment.

How to install

Prerequisites:

Node.js 24+ with npm (or yarn/pnpm as preferred)
Access to a C64 hardware setup (C64 Ultimate/Ultimate 64) or a VICE runner for experimental testing

Install and run (one of the methods):

Using npx (zero setup)
```
npx -y c64bridge@latest
```

From a local project (recommended for development)

mkdir -p ~/c64bridge && cd ~/c64bridge
npm init -y
npm install c64bridge
node ./node_modules/c64bridge/dist/index.js

From source (contributing/testing)

git clone https://github.com/chrisgleissner/c64bridge.git
cd c64bridge
npm install
npm start

Configure a default MCP file or environment to enable the server to discover its target (REST + zero-page read) as described in the README. The server prints diagnostics on startup and then announces that it is running on stdio (and HTTP if enabled).

Additional notes

Environment variables and configuration tips:

C64BRIDGE_CONFIG: Provide an absolute path to a configuration file if you want explicit settings; otherwise defaults are used (host=c64u, port=80).
LOG_LEVEL: Set to debug for verbose diagnostics; logs go to stderr while stdout is reserved for MCP communications.
If both C64U and VICE backends are configured, the backend selection logic will prefer C64U unless only VICE is configured. You can force a backend with C64_MODE=c64u|vice.

Common issues:

Node.js version mismatch: ensure you’re on Node 24+ as required by the Quick Start.
Port conflicts: ensure the port your MCP server binds to is available, or configure a different port via your config.
If the HTTP bridge is enabled for testing, be mindful that it is disabled by default and should be used sparingly for manual testing.

API notes:

The MCP API exposes tools like c64_config, c64_disk, and others (12 tools total) with various operations. Refer to the MCP API Reference in the repository docs for exact inputs for each tool.
For IDE integrations (e.g., VS Code Copilot Chat), you can register the server under MCP settings to enable prompt-driven control of the C64.