geekychris/amiga_mcp

47 stars 6 forks Quality 60 Trend 49MIT

This project, Amiga DevBench, is a cross-development environment that connects a modern host machine to an emulated or real Amiga via serial, providing live debugging, memory inspection, and full MCP...

Overview

A cross-development environment for Commodore Amiga (68k) that connects a modern host machine to an emulated (or real) Amiga via serial, providing live debugging, memory inspection, variable editing, remote execution, and full MCP integration with Claude Code. Brew-style installer — fetches the source, installs the Python host server, pulls the m68k Docker cross-compiler, builds the bridge daemon + examples, and launches the web UI on http://localhost:3000. Re-running pulls the latest commit and rebuilds in place. The installer requires git, python>=3.10, and Docker. On mac/Linux you can opt into auto-install of missing CLI tools with AMIGA_MCP_AUTO_INSTALL=1. Docker Desktop on macOS/Windows needs a GUI install regardless. FS-UAE itself (you need a Kickstart ROM — see FS-UAE Emulator Setup). The optional patched fs-uae fork with the HTTP debugger is opt-in via AMIGA_MCP_BUILD_PATCHED=1 (Linux + macOS).

README

Amiga DevBench

Develop Amiga software from a modern computer. DevBench provides a web dashboard and MCP tools for building programs, transferring files, running AmigaDOS commands and inspecting an emulated or real Amiga.

New here? Install and verify DevBench. The guide works from an existing checkout and starts with a simulator, so you can verify the host installation before setting up an Amiga.

What you need

Host server: Python 3.10+ and Git, on macOS, Linux or Windows.
A real target: an emulator with your own ROM/OS, or an Amiga, running the amiga-bridge guest program. The simulator needs neither.
Compiling Amiga programs: Docker and the appropriate cross-compiler image. Docker is not needed just to install the Python server or inspect a target with an existing bridge.

Setup in three commands

scripts/setup.sh     # install everything that can be installed (68k, os4 or both)
scripts/doctor.sh    # check every prerequisite; each problem comes with its fix
scripts/start.sh     # start the emulators + devbenches, wait until the Amigas answer

The Kickstart ROM and the AmigaOS 3.x / 4.1 installs are commercial, so doctor.sh keeps reporting them until they’re in place; it says where each goes. The scripts are bash: on Windows, use WSL (or scripts/install.ps1). See SETUP.md for the one-page guide.

The current server is in amiga-devbench/ (Python). The mcp-server/ TypeScript project and amiga-debug-lib/ are deprecated.

Start here

I want to…	Read
Set up and start everything with the scripts	SETUP.md
Install from a checkout and verify it works	Installation guide
Connect Codex CLI or Claude Code	MCP client setup
Use WinUAE or FS-UAE	Dual-emulator setup
Connect an emulator or physical Amiga	Target setup
Set up AmigaOS 4.1 on QEMU	AmigaOS 4 setup
Choose between guest and emulator debugging	Debugger guide
Find a tool or API	Documentation index

How it fits together

Codex / Claude Code ── MCP over HTTP ──┐
                                     ├── DevBench ── serial/TCP ── amiga-bridge
Web browser ───────── HTTP ───────────┘                              (Amiga)

The dashboard is at http://localhost:3000/; the MCP endpoint is http://localhost:3000/mcp. scripts/start.sh runs one DevBench per target: AmigaOS 4 on port 3000 and classic 68k on port 3001. DevBench must stay running while clients use it.

Most guest tools work through the bridge. Emulator-level amiga_fsuae_* tools separately require patched FS-UAE. Installing the Python server does not install an emulator, ROM or AmigaOS.

Browse the examples · Architecture · Scripted installer · MIT license

View this README on GitHub

Install

This server does not publish a one-line install command.

Open the repository installation guide