c64u

This MCP server exposes the Commodore 64 Ultimate REST API as a set of AI-accessible tools. It enables Claude and other MCP clients to control the hardware over your local network—writing and debugging BASIC or machine code, loading and running programs, playing SID/MOD/PRG/CRT content, capturing screenshots, typing and sending keystrokes, managing floppy drives, reading and writing memory, and configuring the device. You’ll interact with model-driven commands such as machine_reset, capture_screen, load_prg_file, run_crt_file, and write_memory to perform complex sequences directly on the C64 Ultimate hardware through natural conversations with your AI assistant. Ensure the C64U_URL environment variable points to your device so the server can communicate with the hardware over REST.

Once running, you can connect Claude Desktop or another MCP client and invoke the available tool calls. For example, you can ask the AI to load a PRG from disk and immediately run it, capture the resulting screen, or pause the CPU for debugging via the DMA control. The toolset is organized into Machine Control, Memory Access, Runners (for SID/MOD/PRG/CRT), Floppy Drives, Configuration, Streams (U64 only), and File Operations, giving you granular control over the device’s state and content.

Prerequisites:

• A Commodore 64 Ultimate device with Web Remote Control Service enabled in Network Settings.
• Python environment available on the host running the MCP server (Python 3.8+ recommended).
• MCP tooling installed (the MCP framework provides the uv command).

Installation steps:

1. Acquire the MCP server source for the C64u project (clone or download).
   • Example (adjust URL as needed): git clone https://github.com/your-org/c64u-mcp-server.git
   • Navigate to the project directory: cd c64u-mcp-server
2. Ensure the Web Remote Control Service is enabled on the C64 Ultimate device (as described in prerequisites).
3. Configure the environment and run the MCP server:
   • Create or edit the Claude Desktop configuration to point to this MCP server (see Claude Desktop section in README).
   • Start the MCP server using the MCP runner: uv run python server.py
4. Verify connectivity:
   • The server should reach the device at the URL specified in C64U_URL.
   • Use the available tools from Claude Desktop to perform actions like loading PRG/CRT, capturing screens, or reading memory.

Tips and common issues:

• Ensure C64U_URL is reachable from the host running the MCP server; use a loopback or local network address as appropriate.
• If you upgrade the C64 Ultimate firmware or change network settings, re-verify the URL and re-run the MCP server.
• When using run_prg_upload or sidplay_upload, ensure base64-encoded payloads are correctly formed in the request.
• If commands fail due to authentication or REST API mismatch, double-check the device’s Web Remote Control Service status and API version compatibility.
• For Claude Desktop integration, keep the mcpServers entry name consistent (e.g., commodore64 or c64u) with your Claude configuration.
• The environment variable section in mcp_config is essential for runtime connectivity; update C64U_URL to your device’s current IP if it changes.
• The server supports a broad range of actions through organized categories; if a tool is not responding, consult the API reference in the README for exact call shapes and required parameters.