Commodore 64 Ultimate — MCP Server

⚠️ Alpha Release

This is an alpha release. It has been tested with my own Ultimate boards and home network setup, but I have not extensively tested all configuration combinations and API endpoints. Consider this a starting point to play and have fun with! Contributions, bug reports, and feedback are welcome.

A Model Context Protocol (MCP) server for the Commodore 64 Ultimate — the official modern Commodore 64 computer. This server enables AI assistants like Claude, ChatGPT, and Cursor to control your C64 via the Ultimate's REST API.

🎯 What is This?

The Commodore 64 Ultimate

The Commodore 64 Ultimate is an official Commodore product — a brand new Commodore 64 for the modern era. Inside, it uses a revision of the Ultimate 64 FPGA mainboard designed by Gideon Zweijtzer of Gideon's Logic. It's not an emulator — it is a real Commodore 64, cycle-accurate and built with modern technology.

The Commodore 64 Ultimate features USB storage, ethernet, HDMI output, and a powerful REST API for remote control. This MCP server leverages that REST API to let AI assistants interact with the C64 directly.

Also Compatible With

This server also works with other products from Gideon's Logic:

| Device | Description | |--------|-------------| | Ultimate 64 | The original FPGA-based Commodore 64 mainboard by Gideon's Logic. | | Ultimate II+ | A cartridge for your original Commodore 64 or C128, adding USB storage, ethernet, drive emulation, and more. |

All Ultimate devices expose the same REST API that this MCP server uses.

What Does This MCP Server Do?

This MCP server acts as a bridge between AI assistants and your Commodore 64 Ultimate (or other Ultimate devices), translating natural language commands into API calls. With it, you can:

Load and run C64 programs (PRG, SID, MOD files)
Read/write C64 memory directly
Mount and create disk images (D64, D71, D81)
Control drive emulation
Manage device configuration
Stream audio/video (Ultimate 64 only)

✨ Features

37 Tools covering all major Ultimate device functionality
Dual Transport Modes: STDIO (local) and SSE (remote/hosted)
Docker Support: Easy containerized deployment
Dynamic Connection: Set C64 connection at runtime
Upload PRG via Base64/URL: Run programs from anywhere
Secure by Default: Non-root Docker container

📋 Available Tools

Connection Management

| Tool | Description | |------|-------------| | ultimate_set_connection | Set the hostname and port of the Ultimate C64 device | | ultimate_get_connection | Get the current connection details | | ultimate_version | Get the REST API version |

Program Execution

| Tool | Description | |------|-------------| | ultimate_run_program | Run a program already stored on the Ultimate's filesystem (USB/SD) | | ultimate_load_program | Load a program into memory without running it | | ultimate_run_prg_binary | Upload and run a PRG from external sources — accepts local file path, base64 data, or URL (details) | | ultimate_run_cartridge | Load and run a cartridge file (.crt) |

Audio Playback

| Tool | Description | |------|-------------| | ultimate_play_sid | Play a SID music file (with optional song number) | | ultimate_play_mod | Play an Amiga MOD music file |

Memory Operations

| Tool | Description | |------|-------------| | ultimate_read_memory | Read up to 256 bytes from a C64 memory address | | ultimate_write_memory | Write hex data to a C64 memory address | | ultimate_write_memory_binary | Write binary file contents to memory |

Drive & Disk Management

| Tool | Description | |------|-------------| | ultimate_mount_disk | Mount a disk image (D64/D71/D81) on drive A-D | | ultimate_unmount_disk | Unmount a disk from a drive | | ultimate_turn_drive_on | Turn on a virtual drive | | ultimate_turn_drive_off | Turn off a virtual drive | | ultimate_set_drive_mode | Set drive type: 1541, 1571, or 1581 | | ultimate_load_drive_rom | Load a custom ROM into a drive | | ultimate_create_d64 | Create a new D64 disk image (35 or 40 tracks) | | ultimate_create_d71 | Create a new D71 disk image | | ultimate_create_d81 | Create a new D81 disk image | | ultimate_create_dnp | Create a new DNP disk image |

Machine Control

| Tool | Description | |------|-------------| | ultimate_reset_machine | Perform a C64 reset | | ultimate_soft_reset | Soft reset (load empty program) | | ultimate_reboot_device | Reboot the Ultimate device | | ultimate_power_off | Power off the Ultimate device | | ultimate_get_machine_info | Get machine information and status | | ultimate_get_machine_state | Get current machine state |

Configuration

| Tool | Description | |------|-------------| | ultimate_get_config_categories | List all configuration categories | | ultimate_get_config_category | Get settings in a category | | ultimate_get_config_item | Get a specific setting value | | ultimate_set_config_item | Set a configuration value | | ultimate_bulk_config_update | Update multiple settings at once | | ultimate_save_config | Save configuration to flash | | ultimate_load_config | Load configuration from flash | | ultimate_reset_config | Reset to factory defaults |

File Operations

| Tool | Description | |------|-------------| | ultimate_get_file_info | Get information about a file on the Ultimate |

Streaming (Ultimate 64 Only)

| Tool | Description | |------|-------------| | ultimate_start_stream | Start video, audio, or debug streaming | | ultimate_stop_stream | Stop an active stream |

📦 Running Programs Remotely

The ultimate_run_prg_binary tool is designed to run PRG files that are not stored on the Ultimate device. This is essential for hosted deployments where the AI assistant needs to upload and run programs from external sources.

Three Input Methods

| Parameter | Use Case | |-----------|----------| | prg_data_base64 | AI embeds the PRG as base64 in the request — ideal for small programs or AI-generated code | | url | Server downloads PRG from any HTTP/HTTPS URL — great for hosted program archives | | file_path | Reads from server's local filesystem — for server-side program storage |

Only one parameter should be provided per call.

Example: Base64-Encoded PRG

The AI can encode a compiled PRG program as base64 and send it directly:

{
  "name": "ultimate_run_prg_binary",
  "arguments": {
    "prg_data_base64": "AQgLCJ4ACJ4ACQoAHgoAoCAKgBQKgP8f..."
  }
}

This is particularly powerful for AI-generated demos — the AI can:

Write 6502 assembly code
Compile it (if tools available) or generate machine code directly
Encode the resulting PRG as base64
Send it to run on the actual C64 hardware

Example: URL Download

Point to a PRG hosted anywhere on the internet:

{
  "name": "ultimate_run_prg_binary",
  "arguments": {
    "url": "https://csdb.dk/getinternalfile.php/12345/game.prg"
  }
}

The MCP server downloads the file and uploads it to the Ultimate device.

Example: Server-Local File

If the PRG is on the MCP server's filesystem:

{
  "name": "ultimate_run_prg_binary",
  "arguments": {
    "file_path": "/workspace/demos/mydemo.prg"
  }
}

Note: For files already on the Ultimate device's storage (USB, SD card), use ultimate_run_program instead.

🚀 Quick Start

Prerequisites

Python 3.11+
A Commodore 64 Ultimate (or Ultimate 64/II+/II+L) on your network
The Ultimate's REST API must be accessible (enabled by default)

Installation

# Clone the repository
git clone https://github.com/yourusername/ultimate64-mcp.git
cd ultimate64-mcp/mcp_hosted

# Install dependencies
pip install -r requirements.txt

Running the Server

Option 1: Environment Variable (Recommended)

# Set your Ultimate device's IP address
export C64_HOST="192.168.1.64"

# Start the server
python mcp_ultimate_server.py

Option 2: Command Line Argument

python mcp_ultimate_server.py http://192.168.1.64

Option 3: Dynamic Connection

Start without a configured host and set it later via the ultimate_set_connection tool:

python mcp_ultimate_server.py
# Server starts, then use ultimate_set_connection tool to connect

The server runs on http://0.0.0.0:8000 by default.

🔌 Transport Modes

SSE Mode (Default) — For Hosted/Remote Access

The default mode uses Server-Sent Events (SSE) for persistent HTTP connections. This is ideal for:

Hosted deployments (cloud, VPS)
Web-based AI assistants
Multi-client scenarios

Endpoints:

| Endpoint | Method | Description | |----------|--------|-------------| | /sse | GET | Establish SSE connection, returns session ID | | /messages?session_id={id} | POST | Send JSON-RPC messages | | /upload-prg | POST | Direct PRG upload endpoint (bypasses MCP for large files) |

SSE Connection Flow:

Client connects to GET /sse
Server sends initial event with session_id and endpoint URL
Client sends JSON-RPC requests to POST /messages?session_id={id}
Responses stream back via SSE

STDIO Mode — For Local Use

For local MCP clients (like Cursor or Claude Desktop), use STDIO mode:

python mcp_ultimate_server.py --stdio
# Or with explicit host:

Ultimate64MCP

Install / Use

README