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-AmigaOS4If the server publishes to npm under a different name, use that package instead — check the repo README.
MCP Server
Model Context Protocol server
Quality Score
Category
Development & EngineeringSupported Platforms
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.
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 foundOur 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.
| Skill | Score | Stars | Updated | Format |
|---|---|---|---|---|
| MCP-AmigaOS4 (this skill)by derfsss | 81 | 10 | 1d ago | MCP Server |
| taste-skillby Leonxlnx | 100 | 116.8k | 8d ago | CLAUDE.md |
| Agent-Reachby Panniantong | 100 | 112.3k | 8d ago | CLAUDE.md |
| rufloby ruvnet | 100 | 81.9k | today | CLAUDE.md |
| headroomby headroomlabs-ai | 100 | 79.8k | today | CLAUDE.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.
Skill content
View source on GitHubMCP-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.runcall. - 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_streamdrive 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/.librarydrivers in resident-init mode and chain a test program against them, all in a single tool call. - See the screen —
wb.screenshotcaptures 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-mcpin 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.*, andinput.*, plus a namespace dispatcher per group. Every tool takes atarget, so the same call works against a QEMU guest or a real machine. (events.subscribe,events.unsubscribe, andevents.test_emitare 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/.deviceinside SandboxVM and get back a structured exit code, a trap classification, and the captured output — without the machine going down with it. Anyexec_cmdcan 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 patchesS: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 inconfig.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
taste-skill
116.8kAgent skills that give coding agents taste: art direction, reference images and a browser check instead of generic AI pages
Agent-Reach
112.3kGive your AI agent eyes to see the entire internet. Read & search Twitter, Reddit, YouTube, GitHub, Bilibili, XiaoHongShu — one CLI, zero API fees.
ruflo
81.9k🌊 The original agent harness. Deploy intelligent multi-player swarms, coordinate autonomous workflows, and build conversational AI systems. Features adaptive memory, self-learning intelligence, federation, vector RAG integration, and native Claude Code / Codex / Hermes and many more Integrated
headroom
79.8kCompress tool outputs, logs, files, and RAG chunks before they reach the LLM. 20% fewer tokens for coding agents, 60-95% fewer tokens for JSON, same answers. Library, proxy, MCP server.
Languages
Trust signals
From repository metadata: license, adoption, age and documentation. Not a code audit — see the Safety scan above for what the skill file itself contains.
