MCP-AmigaOS4

A Model Context Protocol server for driving AmigaOS 4.1 machines — both QEMU guests and real PowerPC hardware — from MCP-aware clients such as Claude Code, Claude Desktop, and IDE plugins.

At a glance

Brings AmigaOS 4.1 inside your AI client. From a single MCP session you can:

• Browse and edit files on the target Amiga, run AmigaDOS commands with captured stdout, upload large binaries with zlib compression and resumable chunks.
• Follow long-running commands — every command is a tracked job with an id, exit code and IoErr. One that outlives its timeout keeps running and can be checked, read or stopped later. The daemon's workers run above ordinary programs, so a busy one cannot starve it.
• Inspect live state — running tasks, opened libraries, mounted volumes, public screens, the last alert (decoded), CPU + cache + AttnFlags.
• Drive QEMU lifecycle — start, stop, screenshot the framebuffer, save / restore VM snapshots, attach a GDB stub for whole-system debug.
• Coordinate a fleet — run one method across any mix of QEMU guests and real hardware in parallel; barrier, quorum, or cross-target file relay.
• Install AmigaOS 4.1 FE end-to-end onto a blank volume — preflight, ISO mount, copy, LHA extract, Kicklayout patch, verify — via a single installer.run call.
• Live X5000 hardware introspection — board / CPU temperatures, voltages, fan PWM/RPM via the Cyrus MCU, plus CCSR registers, TLB walks, and IDebug-driven per-task crash snapshots.
• Out-of-band power control — with the FTDI USB-TTL cable wired to the X5000 P18 / A1222 P15 header, power.on / power.off / power.toggle_stream drive the MCU debug shell directly from MCP. Works regardless of AOS / MCPd state; the only software path to boot a fully-off X5000.
• Iterate on programs and drivers without power-cycling — sandbox.* wraps SandboxVM so a guest segfault no longer takes down the daemon. Edit → upload → run → read structured exit code + trap classification + captured stdout/stderr; load .device / .library drivers in resident-init mode and chain a test program against them, all in a single tool call.
• See the screen — wb.screenshot captures a Workbench screen to PNG on the Amiga and returns it, on real hardware as well as QEMU.
• Drive the UI — input.* synthesises keyboard and mouse events, so an agent can dismiss a requester or click through a GUI installer. Off by default, and openable only by a deliberate action on the target itself; see SECURITY.md.

143 typed MCP tools across 15 namespaces, 8 live resources, verified end-to-end on QEMU Pegasos2 and real AmigaOne X5000 hardware.

New to MCP?

MCP (Model Context Protocol) is how an AI app gets new abilities. The app, called the MCP client (Claude Code, Claude Desktop, an IDE), starts small helper programs called MCP servers, and the AI can then use the tools each server offers.

Three pieces work together here:

 AI app (MCP client)  ->  amiga-fleet-mcp  ->  network  ->  MCPd
 e.g. Claude Code         (MCP server, on        (daemon, on each
                           your PC)               Amiga)

You install amiga-fleet-mcp on your PC and MCPd on each Amiga, then tell your AI app about amiga-fleet-mcp once. After that you just talk to the AI ("what volumes are mounted on my A1222?") and the app starts the server for you in the background. You never need to keep amiga-fleet-mcp running in a terminal yourself.

Quick start

You need Python 3.11 or newer, uv (a Python package manager; plain pip works too, see INSTALL.md), and an MCP client. The steps below use Claude Code.

1. Get the code and install the server (once):

git clone https://github.com/derfsss/MCP-AmigaOS4.git
cd MCP-AmigaOS4/host
uv sync

2. Put MCPd on each Amiga (once). See Installing MCPd below.

3. Describe your Amigas (once). The wizard asks for each machine's name and IP address and writes config.toml where the server will find it:

uv run amiga-fleet-mcp --init

4. Check the setup:

uv run amiga-fleet-mcp --doctor

It checks the config, whether each Amiga answers, and whether the MCPd versions match, and prints a fix next to anything that's wrong. Fix any FAIL line first: usually MCPd isn't running on that Amiga, or the IP address is wrong. Run it again after step 5 to confirm your AI app has the server registered.

5. Tell your AI app about the server (once). Use the full path to the host folder you cloned in step 1:

claude mcp add amiga-fleet -- uv --directory /full/path/to/MCP-AmigaOS4/host run amiga-fleet-mcp

(Shortcut: if you start claude in the root of this repository, its .mcp.json offers the server and you can skip this step there.)

6. Use it. Start Claude Code (claude), type /mcp to see that amiga-fleet is connected, then just ask, for example: "List the volumes on my Amiga." Or pick a ready-made workflow: type /mcp__amiga-fleet__getting_started for a guided tour, or /mcp__amiga-fleet__investigate_crash after a crash.

"It just hangs": if you run plain uv run amiga-fleet-mcp in a terminal, it prints the log folder and your targets, then sits there silently. That is normal. It is waiting for an AI app to talk to it, and only an AI app can. Press Ctrl-C and use step 5 instead.

Using Claude Desktop, VS Code or another app, or installed with pip instead of uv? INSTALL.md § Wiring the server into an MCP client has instructions for each.

Installing MCPd

The Amiga side needs MCPd running on each target. The simplest way is on the Amiga itself: download MCPd-<version>.lha from the latest release, then in a Shell, from the folder you saved it in:

LhA x MCPd-<version>.lha
Execute MCPd/MCPd-Install

The archive is assembled on AmigaOS, so the protection bits are already correct — extract and the daemon runs. (A raw ELF copied over SMB or a USB stick arrives with the executable bit protected and has to be Protect +rwed-ed by hand.)

Once MCPd is running on a target, you can also update it from the PC with python scripts/install_mcpd_autostart.py <target-ip>:4322.

Either way MCPd lands in SYS:System/MCPd/, gains a watchdog, and auto-starts on boot. MCPd has no password: keep the Amigas on a private network (SECURITY.md).

Full detail in INSTALL.md; configuration options in USAGE.md.

Documentation

Topic	Document
What you can do with it	USAGE.md
Full command / method / tool reference	COMMANDS.md
Installing pre-built artefacts	INSTALL.md
Setup spec for AI agents	AGENTS_SETUP.md
Building from source	BUILD.md
Host server (Python) — quickstart	host/README.md
Amiga daemon (C) — quickstart and source layout	mcpd/README.md
Change log	CHANGELOG.md
Contributing	CONTRIBUTING.md
Security policy	SECURITY.md
Credits	ACKNOWLEDGEMENTS.md
Licence	LICENSE (BSD-3-Clause)
Third-party dependencies	THIRD_PARTY_LICENSES.md

New here? Read USAGE.md for the architecture and tool surface, then INSTALL.md to install pre-built artefacts or BUILD.md to build from source.

Overview

MCP-AmigaOS4 is a two-piece system:

• amiga-fleet-mcp — a Python MCP server that runs on the user's workstation. It manages a fleet of one or more AmigaOS 4 targets, fans out operations across them in parallel, and bridges to QEMU for lifecycle, snapshots, and GDB.
• MCPd — a small C daemon running on each AmigaOS 4 target. It exposes filesystem, process, system, debug, and Workbench operations as JSON-RPC 2.0 methods over a 4-byte length-prefix framed TCP connection on port 4322, plus a UDP discovery responder on port 4323.

Capabilities

A summary follows; the full list of tools, resources, methods, and helper scripts lives in COMMANDS.md, with narrative context in USAGE.md.

• 143 typed MCP tools across fs.*, exec.*, sys.*, wb.*, debug.*, qemu.*, fleet.*, tests.*, events.wait, app.notify, notify.*, installer.*, serial.*, power.*, sandbox.*, and input.*, plus a namespace dispatcher per group. Every tool takes a target, so the same call works against a QEMU guest or a real machine. (events.subscribe, events.unsubscribe, and events.test_emit are exposed only as daemon RPC methods, not MCP tools — clients call them directly through the transport.)
• Eight live MCP resources for fleet status, per-target system snapshots, capability reports, and serial logs.
• Parallel multi-target operations (fleet.run_on_all, fleet.barrier, fleet.quorum_run, fleet.relay) with optional per-target tag filters.
• LAN-local target discovery (UDP broadcast).
• QEMU lifecycle management plus snapshot save/load/list/delete.
• IDebug-driven per-task introspection: register / memory read and write, symbolicated stack traces, breakpoint control.
• Live system-state reporting: CPU model, caches, AttnFlags, resource probes, mounted volumes, active assigns, library list, public screens, application registry.
• Crash-survivable program and driver iteration (sandbox.*): run a guest ELF or a resident .library / .device inside SandboxVM and get back a structured exit code, a trap classification, and the captured output — without the machine going down with it. Any exec_cmd can also run its program sandboxed, as a tracked job.
• Tracked command jobs (exec.*): status, incremental output, break signals, and a per-call or configured task priority.
• Screen capture to PNG on the target (wb.screenshot) — works on real hardware, where a QMP framebuffer dump is not an option.
• Keyboard and mouse injection (input.*) for driving Workbench and GUI installers, disabled by default at the daemon.
• Server-pushed events (events.subscribe) plus a long-poll alternative (events.wait).
• Auto-start install integration: a single command deploys MCPd to SYS:System/MCPd/, registers a watchdog wrapper, and patches S:Network-Startup. Boot-to-bind is approximately eleven seconds on an AmigaOne X5000. The daemon announces itself in the kernel debug ring once the port is actually accepting connections, so a boot-time start is observable without a Shell — see mcpd/README.md.
• Per-tool parameter defaults via a [defaults] block in config.toml (dest_volume, sources_dir, machine, iso_filename, exec_priority). Set frequently-repeated values once and skip them in subsequent tool calls; explicit per-call values always override. See USAGE.md § Per-tool defaults.
• Native AmigaOS 4.1 FE installer pipeline (installer.*): preflight, ISO mount, recursive copy, LHA extraction, Kicklayout patching, per-machine staged install, and post-install verification.
• Host-side serial-capture service (serial.*): start / stop / tail background captures of a target's debug UART for kernel-debug output during boot or crash investigation.
• Live X5000 hardware introspection (real-hardware only): Cyrus MCU supervisor protocol over UART (sys.mcu_cmd), Freescale QorIQ CCSR reads (sys.read_ccsr), TLB1 dump (sys.tlb_dump), and (with appropriate care) supervisor-mode physical-address reads (sys.read_pa).

Supported targets

Target	Status
QEMU Pegasos2	Verified end to end, including the installer pipeline
QEMU AmigaOne, SAM460ex	Supported
AmigaOne X5000 (Freescale P5020 / E5500)	Verified on hardware, including power.*, the SoC introspection methods, and UI injection
AmigaOne A1222 / Tabor	Supported; board detection and the simplified install path are in place
AmigaOne X1000 / Nemo	Recognised by board detection

sandbox.* needs a machine with ExtMem, so it is available on X5000, A1222, X1000 and QEMU AmigaOne but not on Pegasos2. power.* and the QorIQ introspection methods are real-hardware features by nature.

See INSTALL.md for runtime requirements per target and the auto-start install procedure, or BUILD.md for cross-compiling MCPd from source.

Requirements

Host: Python 3.11, 3.12, or 3.13, on Windows, Linux, or macOS, with git on PATH at install time. The server is built on the mcp 2.x Python SDK. QEMU features additionally need a qemu-system-ppc binary; power.* needs an FTDI USB-TTL cable wired to the target's MCU header; serial.* needs a serial cable to the target's debug UART.

Target: AmigaOS 4.1 Final Edition with TCP/IP (Roadshow) and z.library v53+. The daemon is a single ~300 KiB PowerPC executable with no other dependencies.

Everything degrades per feature rather than per install: a target without the MCU cable simply reports NotCapable for power.* and keeps the rest of the surface. INSTALL.md § Per-feature prerequisites lists what each group needs.

Licence

BSD 3-Clause. Copyright © 2026 Richard Gibbs.

Third-party dependencies retain their own permissive licences; the full index is in THIRD_PARTY_LICENSES.md. See ACKNOWLEDGEMENTS.md for credits.