chrisgleissner/c64bridge

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:
Fallback:
macOS:
Windows:
Verify the installation:
Expected result: v24.x
2. 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.
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.