SkillAgentSearch skills...

MCP-AmigaOS4

MCP server for driving AmigaOS 4.1 machines (QEMU + real hardware) via Model Context Protocol

Install / Use

claude mcp add derfsss -- npx -y github:derfsss/MCP-AmigaOS4

If the server publishes to npm under a different name, use that package instead — check the repo README.

About this skill
🔌

MCP Server

Model Context Protocol server

Quality Score

81/100

Supported Platforms

Claude Code
Claude Desktop

Tags

Our assessment of MCP-AmigaOS4

MCP-AmigaOS4 scores 81/100 on our quality scale, 3441st of 4,698 Development & Engineering skills we index.

Its MCP Server is 14 KB long, well organised into 11 sections with 6 code examples: a thorough specification that gives an agent plenty to work with.

It has 10 GitHub stars, so there is little community track record yet; judge it on its content.

Substance
30/30
Structure
20/20
Description
12/15
Adoption
4/20
Freshness
15/15

Maintenance, license and trust

  • The repository was last updated yesterday, so MCP-AmigaOS4 is actively maintained.
  • It is released under the BSD-3-Clause license, a permissive license that allows use, modification and commercial use with attribution.
  • Its trust signals score 92/100, with 1 caution from licensing, adoption, age or documentation. These come from repository metadata, not a code audit — read the skill file before letting an agent act on it.

Safety scan

No issues found

Our scan of the whole file found no instruction hijacking, hidden characters, credential access, data exfiltration or destructive commands. An AI review of the same text found nothing harmful.

AI review by kimi-k2.7-code on 2026-11-14. Automated pattern scan on 2026-11-14. It catches known dangerous patterns, not every risk — read a skill before letting an agent act on it.

MCP-AmigaOS4 compared with similar skills

All 4 of these similar skills score higher than MCP-AmigaOS4; compare them before choosing.

SkillScoreStarsUpdatedFormat
MCP-AmigaOS4 (this skill)by derfsss81101d agoMCP Server
taste-skillby Leonxlnx100116.8k8d agoCLAUDE.md
Agent-Reachby Panniantong100112.3k8d agoCLAUDE.md
rufloby ruvnet10081.9ktodayCLAUDE.md
headroomby headroomlabs-ai10079.8ktodayCLAUDE.md

Frequently asked questions

How do I install MCP-AmigaOS4?
Run claude mcp add derfsss -- npx -y github:derfsss/MCP-AmigaOS4. The install tabs above show the steps for each supported agent.
Which AI agents does MCP-AmigaOS4 work with?
It is written for Claude Code and Claude Desktop, as a MCP Server file. Other agents that read the same format can often use it too.
Is MCP-AmigaOS4 safe to use?
Our scan of the whole file found no instruction hijacking, hidden characters, credential access, data exfiltration or destructive commands. An AI review of the same text found nothing harmful. It is BSD-3-Clause-licensed and scores 92/100 on trust signals. Skills are instructions an agent will follow, so read the file before installing it and do not approve commands you do not understand.
Is MCP-AmigaOS4 still maintained?
The repository was last updated yesterday, so MCP-AmigaOS4 is actively maintained.

MCP-AmigaOS4

CI License Python AmigaOS 4.1 FE

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, I

Truncated for display — read the full file on GitHub.

Related Skills

View on GitHub
GitHub Stars10
CategoryDevelopment
Updated1d ago
Forks2

Languages

Python

Trust signals

92/100

From repository metadata: license, adoption, age and documentation. Not a code audit — see the Safety scan above for what the skill file itself contains.

1 low1 info