Commodore 64 Ultimate

You deploy and run the Commodore 64 Ultimate MCP Server to bridge natural language AI assistants with your C64 Ultimate hardware. This server translates your prompts into API calls, enabling you to load programs, read memory, mount disks, control drives, stream media, and manage device configuration from AI copilots or local clients. It supports both local STDIO and remote SSE workflows, and can be run in Docker for easy deployment.

How to use

You connect to the MCP server from your chosen MCP client (such as a local desktop client or a hosted assistant). Start by ensuring the Ultimate device is reachable on your network and that its REST API is accessible. Run the server in STDIO mode for local use or connect over SSE for hosted deployments. Use the available tools to perform actions like loading and running programs, reading or writing memory, mounting disk images, and controlling drive emulation. You can upload PRG files from different sources, including base64 payloads, URLs, or server-local files.

How to install

Prerequisites you need before installing are Python 3.11 or newer and network access to your Commodore 64 Ultimate. You may also run the server in a Docker container for easier management.

# Clone the project repository
# (Replace with your actual repository path when running locally)
git clone https://github.com/yourusername/ultimate64-mcp.git
cd ultimate64-mcp/mcp_hosted

# Install Python dependencies
pip install -r requirements.txt

Additional configuration and run notes

Two primary ways to run the server are available: via an explicit HTTP URL to the Ultimate device or in STDIO mode for local use.

# Option A: Connect to a remote Ultimate device (HTTP)
python mcp_ultimate_server.py http://192.168.1.64

# Option B: Run in STDIO mode for local usage
python mcp_ultimate_server.py --stdio

# Option C: Use an explicit host in STDIO mode
python mcp_ultimate_server.py http://192.168.1.64 --stdio

Transport modes

The server supports both SSE (remote/hosted) and STDIO (local) transport modes.

Direct PRG upload and hosted PRG loading

In addition to running PRGs stored on the Ultimate, you can upload and run PRGs from external sources through the server. This supports base64-encoded payloads, URLs, or server-local files.

Docker deployment

You can run the MCP server in a Docker container for isolation and portability.

# Build the image from the hosted portion
cd mcp_hosted
docker build -t ultimate64-mcp .

# Run with an environment variable for the Ultimate address
docker run -p 8000:8000 -e C64_HOST=192.168.1.64 ultimate64-mcp

# Run with a custom port and explicit host URL
docker run -p 8000:8000 -e C64_HOST=http://192.168.1.64:6464 ultimate64-mcp

# Start without a configured host to set it later
docker run -p 8000:8000 ultimate64-mcp

Client configuration

Configure your MCP clients to connect to the server in either SSE remote mode or STDIO local mode. Use the provided host URL for SSE or the STDIO command with the proper environment variables for local use.

Security considerations

The server runs in a non-root container where possible. It requires network access to the Ultimate device API and should be placed behind a reverse proxy for public deployments. Keep sensitive configuration in environment variables and avoid exposing internal endpoints publicly.

Troubleshooting

If you encounter connection issues, verify that the Ultimate device is powered on and reachable on the network, confirm the REST API is enabled, and test connectivity with a direct request to the device. If you see an error about no C64 host configured, provide the host URL via an environment variable, a command-line argument, or set it later using the connection tool.

Notes on PRG and files

Use the direct PRG upload endpoint for large files or when MCP protocol overhead is undesirable. You can upload PRGs as multipart form data, raw binary, or base64-encoded JSON payloads.

API references and tools overview

This server exposes a broad set of tools to manage the Ultimate device, including connection management, program execution, memory operations, drive and disk management, machine control, and configuration. Each tool is designed to be invoked via the MCP protocol from your AI assistant or client.

Notes on configuration files

A configuration file can provide default settings such as the Ultimate base URL, timeouts, and logging configuration. Environment variables and command-line arguments take precedence over the file configuration.

Appendix

You can adjust and fine-tune the server behavior by combining the options above, choosing the transport mode that best fits your deployment, and using the available tools to control the Ultimate device from your AI assistant or local client.

Available tools

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

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 base64, URL, or local file path

ultimate_run_cartridge

Load and run a cartridge file (.crt)

ultimate_play_sid

Play a SID music file from the C64 memory or filesystem

ultimate_play_mod

Play an Amiga MOD file

ultimate_read_memory

Read memory from a C64 address (up to 256 bytes)

ultimate_write_memory

Write hex data to a C64 memory address

ultimate_write_memory_binary

Write binary payloads to memory from a file

ultimate_mount_disk

Mount a disk image (D64/D71/D81) on a 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

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

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

ultimate_get_file_info

Get information about a file on the Ultimate

ultimate_start_stream

Start video, audio, or debug streaming (Ultimate 64 only)

ultimate_stop_stream

Stop an active stream (Ultimate 64 only)