📰 newsreader

An MCP server that gives Claude hands on a real Amiga. It can run AmigaDOS commands, read and write files, list drawers, inspect the machine, capture the screen, and move the mouse and type on it.

You describe the problem; Claude pokes at the actual hardware.

That is Claude clicking into a Shell on an A4000/060, typing a command, and pressing Return — the umlauts routed through the Amiga's own German keymap.

┌──────────────┐ MCP over stdio ┌──────────┐ framed TCP ┌────────────┐

│ Claude Code │ ◄─────────────────► │ amimcp │ ◄────────────► │ amiagent │

│ (your Mac/PC)│ JSON-RPC 2.0 │ (python) │ port 7846 │ (the Amiga)│

└──────────────┘ └──────────┘ └────────────┘

Two halves:

amimcp

— the MCP server, on the machine running Claude. Pure Python standard library: no venv, no pip, no lockfile to rot between the day you set this up and the evening two years later when the Amiga won't boot.amiagent

— a small C daemon on the Amiga. AmigaOS 2.04 and up, bare 68000, ~85 KB, needs nothing butbsdsocket.library

.

Together those are enough to actually work: read a Startup-Sequence and fix it, cross-compile a binary and push it over and run it, launch a GUI program and drive it by clicking, or just look at what the machine is showing when it has gone wrong.

Two things are worth knowing before you drive a GUI:

- Watch cheaply. A full 1080p truecolour frame is ~6 MB over a ~1 MB/s link —

about 7 seconds. Reading one status line as a region is effectively free, and

amiga_region_changed

answers "has it finished drawing?" in four bytes. Poll with hashes; capture pixels only when you need to look. - Two kinds of pointer.

amiga_click

warps the Intuition pointer, which Intuition applications follow. SDL programs — games, ScummVM — track raw mouse deltas and keep their own cursor, so they never see the warp and the click lands wherever they still believe the pointer is. Passrelative: true

for those. And an Amiga menu is opened by holding the right button and moving, so it needsamiga_drag

, not a click.

Grab amiagent-0.5.3.lha

and unpack it on the Amiga. It contains amiagent

(68000, runs on everything)

and amiagent.020

(68020+).

amipkg install amiagent

Needs an m68k-amigaos cross-toolchain — AmigaPorts/m68k-amigaos-gcc, the maintained descendant of bebbo's amiga-gcc. (Bebbo's own repository is gone as of 2026-08-07; AmigaPorts is where it lives now.) Cross-compile on any machine that has it:

cd agent && make # 68000 baseline, runs on every Amiga

cd agent && make CPU=68020 # 68020+ build

Copy the resulting amiagent

to the Amiga.

If the link fails with an undefined

IntuitionBase

, your toolchain doesn't auto-open intuition/graphics. Rebuild withmake OWNBASES=1

.

Bring up your TCP/IP stack (Roadshow, AmiTCP, or the emulator's bsdsocket

emulation), then from a Shell:

amiagent TOKEN=pickasecret

It prints that it is listening on port 7846 and waits. Ctrl-C stops it; if

you backgrounded it, find it with Status

and Break <n> C

.

Options: PORT/N

(default 7846), TOKEN/K

, QUIET/S

.

To start it at boot, add this to S:User-Startup

, after your TCP stack

comes up:

run >NIL: amiagent TOKEN=pickasecret QUIET

./install.sh 192.168.1.42 pickasecret

That probes the Amiga first, then registers the server with Claude Code. Or do it by hand:

claude mcp add amiga \

--env AMIGA_HOST=192.168.1.42 \

--env AMIGA_TOKEN=pickasecret \

-- python3 /path/to/amimcp/server/amimcp.py

For Claude Desktop, add this to claude_desktop_config.json

:

{

"mcpServers": {

"amiga": {

"command": "python3",

"args": ["/path/to/amimcp/server/amimcp.py"],

"env": {

"AMIGA_HOST": "192.168.1.42",

"AMIGA_TOKEN": "pickasecret"

}

}

}

}

Start a new session and ask Claude to check the Amiga.

MCP is an open standard, and server/amimcp.py

is an ordinary stdio MCP

server: it speaks JSON-RPC over stdin/stdout and takes its configuration from

environment variables. Anything that can launch an MCP server can therefore

drive the Amiga — the server does not know or care which model is on the other

end.

Only the config file shape differs. OpenAI Codex CLI (~/.codex/config.toml

)

uses TOML:

[mcp_servers.amiga]

command = "python3"

args = ["/path/to/amimcp/server/amimcp.py"]

env = { AMIGA_HOST = "192.168.1.42", AMIGA_TOKEN = "pickasecret" }

Google Gemini CLI, Cursor, Zed, Cline, Continue,

Windsurf, LM Studio and Goose take the same mcpServers

JSON block

shown above for Claude Desktop, in their own settings file. Check your client's

current docs for the exact path — these move.

So by model:

Tested against Claude Code and Claude Desktop. The rest follow from it being a standard stdio server rather than from me having run all of them; if one needs something different, please open an issue and say what.

Requires Python 3 — standard library only, no pip install

, no venv.

AMIGA_HOST=192.168.1.42 AMIGA_TOKEN=pickasecret python3 server/amimcp.py --probe

This skips MCP entirely, so a failure here is a network or agent problem rather than a client one.

amiagent

runs arbitrary commands for anyone who can reach its port, and the

protocol is unencrypted. That is a deliberate trade: classic Amigas have no TLS

without AmiSSL, and requiring AmiSSL just to reach the machine you are trying to

repair defeats the purpose.

So: set a TOKEN

, keep it on a LAN you trust, and never forward the port.

Without a token, anything on your network segment can run Format

on your

system partition. The agent warns loudly when started without one.

The token is compared byte-for-byte (so A4000

and a4000

are different

tokens) and travels in cleartext. It stops a stray port scan, not someone with a

packet sniffer on your LAN.

An A4000/060 running Kickstart 47.115 / Workbench 47.5 (AmigaOS 3.2.3) with

Roadshow and a 1920×1080 Picasso96 RTG screen. Confirmed against that machine:

shell with stdout+stderr and return codes, file read/write, directory listing,

system info, native truecolor screen capture through cybergraphics.library

,

SGrab capture as the fallback, mouse move/click, and typing — including

äöü ÄÖÜ ß

correctly produced through the machine's German keymap.

Transfer runs at roughly 830 KiB/s, so a full 1920×1080 truecolor grab is 6.2 MB and about 7 seconds on the wire; the PNG that reaches Claude is around 850 KiB.

- One command at a time. Commands run in a child process with a deadline,

so a program waiting for input no longer wedges the agent — everything else

keeps working and

amiga_break

sends it Ctrl-C. But a stuck command does block lateramiga_shell

calls until it is broken or finishes. - The client and agent must be the same version. The wire format changed in

0.3.0; mixing 0.2.0 with 0.3.0 produces confusing errors rather than a clean

refusal.

--probe

prints the agent's version. - stderr needs OS 3.2+.

SYS_Error

arrived indos.library

v47, so on 3.2 and later stderr is captured and appended after a--- stderr ---

marker. Older systems get stdout only. - Screenshots take one of two routes. The agent captures planar screens

itself (OS 3.0+, ≤256 colours) and truecolor/RTG screens through

cybergraphics.library

, which Picasso96 and CyberGraphX both provide. If neither fits, it falls back to runningC:sgrab

on the Amiga and fetching the file — SGrab compresses on the Amiga, so it transfers far less. SGrab's JPEG mode additionally needsjpeg.library

; PNG does not. - One command at a time, one connection at a time.

- 16 MiB frame cap in both directions.

PROTOCOL.md

documents the wire format and, more usefully, why

each part looks the way it does — the framing, why there is one command per

connection, how input events are injected, and the System()

file-handle

ownership rule that caused the first real bug found on hardware.

tests/fake_agent.py

speaks the same wire protocol against a sandbox directory,

so you can build and debug the whole stack on your desktop and then change one

environment variable to hit real hardware:

python3 tests/fake_agent.py --port 7846 --root /tmp/fakeamiga

AMIGA_HOST=127.0.0.1 python3 server/amimcp.py --probe

It is a test double, not an emulator: EXEC

understands a handful of

AmigaDOS-shaped commands rather than actually running AmigaDOS.

./run_tests.sh # 69 tests, no hardware and no cross-compiler needed

PROTOCOL.md the wire format, and why it looks like that

agent/amiagent.c the Amiga daemon

agent/proto.h constants shared with the Python side

agent/Makefile m68k-amigaos-gcc build

agent/vendor/cgx/ CyberGraphX interface files (see its README)

server/amimcp.py MCP server (stdio JSON-RPC)

server/amiga.py wire protocol client

server/png.py chunky/RGB → PNG, stdlib zlib

tests/fake_agent.py host-side stand-in for the Amiga

tests/ end-to-end and protocol-drift tests

tools/amibench/ CPU/memory benchmark for comparing Amigas

tools/lhapack/ builds the release archive (macOS has no LHA writer)

install.sh register with Claude Code

tools/amibench

is a small CPU/memory benchmark for answering

"how much faster is machine A than machine B". It is standalone — it needs

nothing else installed — and there is a ready-made binary on the

releases page.

It is built for 68020 so one identical binary runs on an 020, an 040, an 060 and on Emu68's JIT; comparing separate builds would measure the compiler as much as the machine. Each phase self-calibrates to a ≥2 s window, because a fixed workload is useless across a 70× speed range — a PiStorm finished an entire 50 MB memcpy inside a single 1/50 s tick.

An A1200 + PiStorm32-lite measured ~73× an A4000/060 at 50 MHz on CPU and Fast RAM, reproducible to within 3% across two runs, and cross-checking against SysInfo putting the same pair 50.1× apart. Chip RAM does not follow — see its README for why that matters more than the headline number.

Apache 2.0 — see LICENSE. Vendored CyberGraphX interface files keep

phase5's terms; see NOTICE and

agent/vendor/cgx/README.md

.