C64UltimateMcpServer

C64 Ultimate MCP Server

English | [Polski](#-c64-ultimate-mcp-server-polski)

> ⚙️ This project was built 100% using AI Agent prompts - Every line of code, configuration, and documentation was generated through conversational prompts to GitHub Copilot Agent.

Comprehensive Model Context Protocol (MCP) server for the Commodore 64 Ultimate device with 46 MCP tools, 15 MCP prompts, and 55 embedded documentation resources. Built in C# with enterprise-grade architecture, type safety, and comprehensive API coverage.

License: MIT License (see [LICENSE](LICENSE) file)

🎥 Demo Video

[](https://www.youtube.com/watch?v=1q80quIIkV0?ccloadpolicy=1&cclangpref=en)

⚡ Key Features

• Complete Ultimate 64 API Support: 46 MCP tools covering the Ultimate REST API plus PRG generation workflows
• MCP Prompts Support: 15 prompt templates exposed through prompts/list and prompts/get
• BASIC to PRG Compilation: Real-time compilation of BASIC V2 source code to executable PRG files
• MCP Resources: 55 embedded documentation resources (BASIC specs, Assembly guides, examples, source catalogs, Kernal API, memory maps, graphics, sound, I/O, drive, printer, keyboard/control codes, disassembly)
• Separated Client Library: Reusable C64UltimateClient NuGet package with clean async API
• Clean Architecture: Client → Service → MCP wrapper pattern with proper DI
• Streamable HTTP Transport: Remote multi-client support with session-aware MCP interactions
• Streaming Support: Video, audio, and debug streaming capabilities
• Binary File Support: Upload PRG files via base64, file path, or URL
• ASP.NET Core 8.0/10.0: Modern, high-performance web framework
• Enterprise Configuration: appsettings.json with environment overrides
• Type Safety: C# static typing with full null-safety and nullable reference types
• Structured Logging: Separate loggers for client and service layers
• Production-Ready: Zero errors/warnings, comprehensive error handling
• Agent Integration: Works with Continue, Copilot, Cody, Cursor, Claude Desktop

🧠 Embedded Knowledge Resources

The server exposes a curated MCP resource catalog under c64://resources/index. The resources are stored in C64UltimateMcpServer/Resources/data as OKF-style markdown or plain-text assets and are wired through C64ResourceCatalog and C64ResourceProvider.

Recent additions make the resource set more useful for agents writing Commodore 64 games, demos, and hardware-aware programs:

• Source provenance: c64://sources/classic-c64-references records the classic C64 books/manuals used as source material without requiring host-specific source paths.
• Example routing: c64://examples/index and c64://examples/game-demo-patterns route agents to embedded examples that work with the built-in PRG generators and portable game/demo pattern notes.
• Ready-to-use assembly examples: c64://examples/assembly/raster-bars-demo, c64://examples/assembly/sprite-demo, and c64://examples/assembly/joystick-game-loop provide compact, tested starting points for demos and games.
• Generator-tested adaptations: c64://examples/assembly/hires-dot-burst-generator and c64://examples/assembly/dreadline-fastscroll-generator preserve source ideas from upstream C64 sources/C64AIToolChain in forms that compile through ultimate_generate_assembly_prg.
• Embedded reference sources: c64://examples/assembly/hires-fire-line-demo and c64://examples/assembly/hires-line-draw-library preserve the upstream HIRES graphics demo/library inside the MCP server.
• Practical coding references: c64://assembly/ml-kernal-quickstart, c64://memory/mapping-notes, expanded KERNAL API notes, and improved sprite/charset guidance help agents choose safe memory locations, KERNAL calls, and VIC-II workflows.

The embedded examples are intentionally small and aligned with the built-in BASIC/assembly PRG generators. Larger C/cc65 examples are indexed as reference material until a C compiler workflow is added.

🚀 Quick Start

# 1. Build
dotnet build

# 2. Configure (optional, defaults to http://192.168.0.120)
export Ultimate__BaseUrl=http://your-c64-ultimate-ip:port

# 3. Run
dotnet run

# 4. Server starts on http://localhost:8080

📦 Installation

Requirements

• .NET 10.0 SDK - Download
• C64 Ultimate device - On your network
• Curl or HTTP client - For testing
• Docker (optional) - Download

Setup

git clone https://github.com/ch0mik/C64UltimateMcpServer.git
cd C64UltimateMcpServer
dotnet build
dotnet run

⚙️ Configuration

appsettings.json

{
  "Ultimate": {
    "BaseUrl": "http://192.168.0.120"
  }
}

Environment Variable

Ultimate__BaseUrl=http://192.168.0.120

Docker

environment:
  - Ultimate__BaseUrl=http://192.168.0.120

🤖 Agent Integration

Continue IDE (Recommended)

1. Install Continue - https://continue.dev
2. Configure .continue/config.json:

{
  "models": [
    {
      "title": "Claude",
      "provider": "openai",
      "model": "claude-3-5-sonnet"
    }
  ],
  "mcp_servers": {
    "c64-ultimate": {
      "url": "http://localhost:8080"
    }
  }
}

1. Use in Chat:

@C64 reboot the device
@C64 load and run /games/loderunner.prg
@C64 what config categories are available?

VS Code Chat (GitHub Copilot)

1. Install - GitHub Copilot Chat extension
2. Configure .vscode/settings.json:

{
  "github.copilot.chat.mcpServers": [
    {
      "name": "C64 Ultimate",
      "type": "streamable-http",
      "url": "http://localhost:8080"
    }
  ]
}

1. Use:

@C64 reboot device
@C64 mount disk /games/disk1.d64

Cody (Sourcegraph)

cody mcp add c64-ultimate http://localhost:8080

Then in Cody:

Ask Cody: Use C64 Ultimate MCP to reboot the device
Ask Cody: List all available config categories

Cursor IDE

1. Configure .cursor/mcp.json:

{
  "servers": [
    {
      "name": "C64 Ultimate",
      "type": "http",
      "url": "http://localhost:8080"
    }
  ]
}

1. Use slash commands:

/c64 reboot device
/c64 load program

🛠️ Tools (46 Total)

Machine Control (5)

• ultimateresetmachine - Soft reset C64 (preserves configuration)
• ultimaterebootdevice - Full device restart (reinitializes cartridge)
• ultimatepausemachine - Pause machine execution
• ultimateresumemachine - Resume machine execution
• ultimatepoweroff - Power off C64

Program Management (7)

• ultimategeneratebasic_prg - Generate PRG from BASIC source code with token conversion
• ultimategenerateassembly_prg - Generate PRG from 6510 assembly source code
• ultimateloadprogram - Load PRG program from filesystem
• ultimaterunprogram - Load and execute PRG from disk
• ultimaterunprg_binary - Execute program from binary data, URL or file
• ultimateruncartridge - Load and run cartridge
• ultimatemenubutton - Simulate menu button press

Memory Management (5)

• ultimatereadmemory - Read C64 RAM memory contents
• ultimatewritememory - Write to RAM memory
• ultimatewritememory_binary - Write binary data to memory
• ultimategetdebug_register - Read debug register
• ultimatesetdebug_register - Write to debug register

Audio Playback (5)

• ultimateplaysid - Play SID file with optional song number
• ultimateplaysid_binary - Play SID from binary data, URL or file
• ultimateplaymod - Play Amiga MOD file
• ultimatestartstream - Start audio/video/debug stream
• ultimatestopstream - Stop active stream

Drive Management (7)

• ultimategetdrives - Get information about all disk drives
• ultimatemountdisk - Mount disk image from filesystem or binary data
• ultimateunmountdisk - Unmount disk image
• ultimateresetdrive - Reset selected disk drive
• ultimatesetdrive_mode - Change drive operating mode
• ultimateturndrive_on - Power on disk drive
• ultimateturndrive_off - Power off disk drive

Disk Creation (4)

• ultimatecreated64 - Create 1541 disk image (D64)
• ultimatecreated71 - Create 1571 disk image (D71)
• ultimatecreated81 - Create 1581 disk image (D81)
• ultimatecreatednp - Create Native Partition disk image (DNP)

ROM Management (1)

• ultimateloaddrive_rom - Load custom ROM to disk drive

File Management (1)

• ultimategetfile_info - Get file information

Configuration Management (8)

• ultimategetconfig_categories - Get list of available configuration categories
• ultimategetconfig_category - Get all settings in a category
• ultimategetconfig_item - Get single configuration value
• ultimatesetconfig_item - Set configuration value
• ultimatebulkconfig_update - Update multiple settings at once
• ultimatesaveconfig - Save current configuration to flash
• ultimateloadconfig - Load configuration from flash
• ultimateresetconfig - Reset configuration to defaults

Connection Management (2)

• ultimategetconnection - Get current connection settings
• ultimatesetconnection - Change device hostname/port

System Information (1)

• ultimate_version - Get C64 Ultimate API version

💬 Prompts (15 Total)

• basic-program - BASIC program workflow prompt
• assembly-program - Assembly workflow prompt
• assembly-prg-build - Assembly-to-PRG build workflow prompt
• sid-music - SID composition workflow prompt
• graphics-demo - VIC-II graphics demo workflow prompt
• printer-job - Printer workflow prompt
• memory-debug - Memory inspection / patch workflow prompt
• drive-manager - Drive management workflow prompt
• game-loop-basic - BASIC game loop workflow prompt
• petscii-ui-layout - PETSCII UI layout workflow prompt
• keyboard-input-c64 - Keyboard input workflow prompt
• sprite-marker-workflow - Sprite marker workflow prompt
• sid-sfx-basic - SID SFX workflow prompt
• c64basicprogram_prompt - Legacy BASIC prompt template exposed as an MCP prompt
• c64sidmusic_prompt - Legacy SID prompt template exposed as an MCP prompt

Important: prompts are MCP prompts, not tools. Use prompts/list and prompts/get for prompts, and tools/call only for tools.

Summary (46 Total Tools)

• Machine Control: 5 tools
• Program Management: 7 tools
• Memory Management: 5 tools
• Audio Playback: 5 tools
• Drive Management: 7 tools
• Disk Creation: 4 tools
• ROM Management: 1 tool
• File Management: 1 tool
• Configuration Management: 8 tools
• Connection Management: 2 tools
• System Information: 1 tool

📚 Resources (55 Total)

Embedded documentation accessible via MCP Inspector at http://localhost:8000:

BASIC Resources (9)

• c64://basic/spec - BASIC V2 Language Specification
• c64://basic/pitfalls - BASIC Pitfalls and Common Gotchas
• c64://basic/examples/hello-world - Hello World Example
• c64://basic/examples/joystick - Joystick Input Example
• c64://basic/examples/bounce - Bounce Animation Example
• c64://basic/examples/wave - Wave Animation Example
• c64://basic/examples/entchen-petscii - PETSCII example
• c64://basic/examples/games/snake - Snake example
• c64://basic/examples/games/tictactoe - Tic-tac-toe example

Assembly Resources (5)

• c64://assembly/spec - 6510 Assembly Language Specification
• c64://assembly/tooling-notes - 6510 Assembly Tooling Notes for MCP compiler subset
• c64://assembly/ml-kernal-quickstart - Machine-language KERNAL quickstart
• c64://assembly/examples/hello-sys - Minimal SYS-start assembly example
• c64://assembly/examples/text-scroll - VIC-II text scroller (softscroll + hardscroll) example

Memory Resources (5)

• c64://memory/map - C64 Memory Map (0x0000-0xFFFF)
• c64://memory/kernal - Kernal Memory Map (ROM $E000-$FFFF)
• c64://memory/low - Low Memory Map (0x0000-0x03FF)
• c64://memory/mapping-notes - Practical memory placement and banking notes
• c64://memory/symbols - Common memory symbols

Graphics Resources (4)

• c64://graphics/vic-spec - VIC-II Chip Specification
• c64://graphics/charset - Character Set Reference
• c64://graphics/petscii - PETSCII style guide
• c64://graphics/sprite-charset-best-practices - Sprite/charset guidance

Sound Resources (4)

• c64://sound/sid-spec - SID Chip specification
• c64://sound/sid-programming - SID programming guide
• c64://sound/sid-file-structure - SID file format documentation
• c64://sound/sidwave - SIDWAVE format reference

I/O Resources (5)

• c64://io/cia-spec - CIA Chip specification
• c64://io/io-spec - I/O Port specification
• c64://io/joystick - Joystick reference
• c64://io/keyboard-c64 - Keyboard matrix reference
• c64://io/control-codes-c64 - Control code reference

Drive Resources (1)

• c64://drive/spec - 1541/1571/1581 Disk Drive Specification

Printer Resources (6)

• c64://printer/commodore-spec - Commodore Printer Specification
• c64://printer/epson-spec - Epson Printer Specification
• c64://printer/spec - Unified printer guide
• c64://printer/prompts - Printer prompt routing guide
• c64://printer/commodore-bitmap - Commodore bitmap printing
• c64://printer/epson-bitmap - Epson bitmap printing

API Resources (2)

• c64://api/basic-api - BASIC callable API reference
• c64://api/kernal-api - Kernal callable API reference

Example Resources (11)

• c64://examples/index - Example source routing index
• c64://examples/game-demo-patterns - Game and demo pattern notes
• c64://examples/assembly/dreadline-fastscroll-generator - Dreadline-derived fastscroll generator example
• c64://examples/assembly/raster-bars-demo - Raster bars assembly demo
• c64://examples/assembly/sprite-demo - Single sprite assembly demo
• c64://examples/assembly/joystick-game-loop - Joystick game loop assembly skeleton
• c64://examples/assembly/hires-fire-line-demo - HIRES fire/line demo reference
• c64://examples/assembly/hello-world-kernal - KERNAL hello world assembly example
• c64://examples/assembly/hires-dot-burst-generator - HIRES dot burst generator example
• c64://examples/assembly/hires-line-draw-library - HIRES line draw library reference
• c64://examples/basic/token-control-codes - BASIC token/control-code example

Example provenance:

| Resource | Origin | Notes | | --- | --- | --- | | c64://examples/assembly/raster-bars-demo | C64 Ultimate MCP Server | Compact generator-tested demo written for ultimate_generate_assembly_prg. | | c64://examples/assembly/sprite-demo | C64 Ultimate MCP Server | Compact generator-tested sprite setup/movement demo. | | c64://examples/assembly/joystick-game-loop | C64 Ultimate MCP Server | Compact generator-tested joystick/game-loop skeleton. | | c64://examples/assembly/hello-world-kernal | upstream C64 sources | Embedded adaptation of the upstream C64 assembly hello-world example for the built-in assembly PRG generator. | | c64://examples/basic/token-control-codes | upstream C64 sources | Embedded BASIC token/control-code example for the built-in BASIC PRG generator. | | c64://examples/assembly/hires-fire-line-demo | upstream C64 sources | Embedded reference source for the HIRES fire/line demo; kept as reference because it uses an include-style library split. | | c64://examples/assembly/hires-line-draw-library | upstream C64 sources | Embedded reference source for the HIRES line drawing and dot-stepping library. | | c64://examples/assembly/hires-dot-burst-generator | upstre

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: ch0mik
• Source: ch0mik/C64UltimateMcpServer
• License: MIT

Install and usage instructions live in the source repository linked above.