AppleBridge

AppleBridge

Remote Apple Events for System 7 — control, monitor and build on a classic Mac from outside, with AI or without.

AppleBridge puts a classic Macintosh on the end of a socket — an emulated one under Basilisk II or SheepShaver, or a real 68k machine over a serial cable. At its core it gives System 7 what Mac OS X later shipped as remote Apple Events: any program on the network can send commands into the Mac — through MPW's ToolServer and the daemon's native verbs — and read real output back, plus extras the original never had, like screenshots of the guest's own screen for context.

That makes it two things at once:

• A low-level remote-control plane for classic Mac OS. No AI required: the bridge is a

host server and a guest daemon speaking a plain TCP (or serial) protocol, and anything — a script, a CI job, nc on a command line — can control, monitor and manage System 7 with it.

• A full AI development environment. 31 MCP tools expose the whole surface to Claude Code

out of the box, but you can throw whatever model you want at the problem — frontier models already know MPW, THINK C and Inside Macintosh — so software can be written, compiled, linked, run and debugged on the Mac in natural language.

A whole System 7.5.3 screen with nothing running but AppleBridge — a session of ordinary system work arriving over the bridge: volumes, directory listings, the installer's own log, the Startup Items folder, and the footer carrying the transport, the RX/TX counters and the error count. The daemon itself is faceless; it normally has no window at all, and this Verbose console is optional, toggled with MONITOR:1. The image was captured by the daemon out of the emulated framebuffer, streamed over the bridge, and decoded to PNG on the host — so it is the guest's own screen, not a picture of a window on someone's Mac.

What You Can Do

You: "Create a counter app that counts from 0 to 20"
Claude: [Writes C code, compiles with SC, links, and runs on System 7.6.1]
Result: Classic Mac app running in authentic 1990s environment

Examples:

• Build classic Mac apps - Claude writes, compiles, and tests 68k code
• Develop in assembly - Create apps using MPW assembler with AI assistance
• Automate MPW workflows - Compile, link, and execute remotely
• Debug with feedback - Full command output capture via ToolServer
• Learn retro programming - AI tutor for 68k assembly and Toolbox APIs

On my bootstrap way developing AppleBridge, I had the desire to have something like 'IP-Runner' ($WINDOWS) for AppleTalk.\ And like in a ferry tail, I typed my wish and BANG! MacNetScan was born: https://macintoshgarden.org/apps/macnetscan

AppleBridge on a command prompt isn't really sexy with its STATUS and DISKLIST commands.\ But it was designed for Claude Code, talking to folks like ToolServer and - oh Boy - MPW!

In the Garden and the Repository, there are treasure chests of powerful Macintosh tools to simply plug-in and compile what you want in plain Assembler or C.\ These days in the 80/90-ties, someone able to program MPW was someone with Macintosh superpower. - I did work for the big players, even they could not afford MPW. - At least not for us marketing folks.

I set the bar even higher and implemented mouse and system menu operations in MCP.\ That's because the last training I gave to Symantec in Amsterdam, got me my own THINK C compiler. And a short while back (~1993), I studied and swallowed Dave Mark's 'Macintosh C Programming' books, which I bought at Barnes&Nobles on a biz trip to the States.

That was really a hart nut for Claude Code, but after introducing how to screenshot, operating the mouse and making use of Macintosh Command Keys, Claude started to explore available libraries and did his thing:

You can read the full story here: Building a THINK C++ Graphics Demo

And I was really impressed about what we could establish within three days. -\ Nope! Claude Code made it in about 3 minutes and the biggest challenge were time consuming screenshots.\ But that was the proof, with AppleBridge big things become possible.

But back to MPW. It's syntax is based on Unix like commands and here the three Studges: Claude Code, ToolServer and MPW come together for a perfect play.\ In total over 6 months of time I established AppleBridge in a bootstrap way. AppleBridge did some heritage from ClaudeBridge . You can already see the REZ part in it and here the programming did really start.

Step-by-step I established 31 MCP tools, that allow Claude Code to access the Macintosh System and almost all toggles of MPW, Think C or even Microsoft FoxPro and yes, you name it!\ You can become creative yourself and build your own Macintosh software dream. Boundless, if there wouldn't be system limits like memsize or CPU speed.

What doesn't work? - Initially I planned implementing a browser with TLS support, simply looking at modern https:// web pages.\ That is not possible or better feasible: Libraries (TLS) are missing and need to be written yourself, compute speed would let you wait almost endlessly.\ And here we simply hit the system limits, like in real life. J

Architecture

flowchart TB
    subgraph Host["Host (macOS)"]
        Claude["Claude Code\n(AI/LLM)"]
        MCPServer["mcp/server.py\n(MCP, stdio)"]
        HostSrv["host_server.py\n:9001 control, :9000 daemon"]
    end

    subgraph BAII["Emulator (Basilisk II / SheepShaver) — or real 68k hardware"]
        subgraph Mac["Classic Mac (System 7.5.3+ / Mac OS 9)"]
            AppleBridge["AppleBridge Daemon\n(C, 68k)"]
            OT["OpenTransport / MacTCP\n(or Serial)"]
            ToolServer["ToolServer\n'MPSX'"]
            MPWShell["MPW Shell\n'MPS '"]
        end
    end

    Claude -->|"MCP (stdio)\ntool calls"| MCPServer
    MCPServer -->|"localhost TCP :9001\nforward command"| HostSrv
    HostSrv |"daemon socket :9000\n(Mac connects OUT)"| OT
    OT |"Network layer"| AppleBridge
    AppleBridge -->|"Apple Events\n'misc'/'dosc'"| ToolServer
    AppleBridge -.->|"fallback"| MPWShell
    ToolServer -->|"✓ Returns output\nvia AE reply"| AppleBridge
    MPWShell -.->|"✗ Empty reply\noutput to worksheet"| AppleBridge

    style Claude fill:#e1f5ff
    style MCPServer fill:#fff4e1
    style OT fill:#e1ffe1
    style AppleBridge fill:#ffe1e1

Communication Flow

sequenceDiagram
    participant CC as Claude Code
    participant MH as Host (mcp + host_server.py)
    participant OT as OpenTransport
    participant AB as AppleBridge Daemon
    participant TS as ToolServer

    Note over AB,MH: Initial connection
    AB->>OT: Initialize OpenTransport
    OT->>MH: TCP Connect to :9000
    MH-->>OT: Connection established
    OT-->>AB: Connected

    Note over CC,MH: MCP Layer
    CC->>MH: MCP tool call (port :9001)mpw_execute("Echo 'Hello'")

    Note over MH,AB: TCP/OpenTransport Bridge
    MH->>OT: Forward command via TCP
    OT->>AB: COMMAND:len\n

    Note over AB,TS: Apple Events Layer
    AB->>TS: Apple Event 'misc'/'dosc'
    TS->>TS: Execute: Echo 'Hello'
    TS-->>AB: AE Reply (Items:3)STDOUT, STDERR, STATUS

    Note over AB,MH: Response path
    AB->>OT: STATUS:0\nSTDOUT:len\n
    OT->>MH: TCP response
    MH-->>CC: MCP tool result{success: true, output: "Hello"}

The four layers

1. MCP — Claude Code ↔ mcp/server.py over stdio. Optional: it adds the 31 tools

and natural language, and nothing below it depends on it.

1. Control — mcp/server.py (or any socket client) ↔ host_server.py on localhost:9001.
2. Bridge — the guest daemon ↔ host_server.py on :9000. The daemon dials OUT, so

a guest behind NAT needs no inbound route. Carried by Open Transport, MacTCP or a serial line, chosen with NET=.

1. Apple Events — the daemon ↔ ToolServer / MPW Shell. Optional: this is the command

tier. ToolServer returns output; MPW Shell runs the command and replies empty.

Layers 1 and 4 are the ones you can leave out, and each is a tier you do not have rather than a broken install. Why OT and MCP is not one layer twice: [docs/ARCHITECTURELAYERS.md](docs/ARCHITECTURELAYERS.md).

Quick Start

Prerequisites

Host (macOS):

• Basilisk II, SheepShaver and even a genuine 68kMac(!) on System 7 with a guest that boots. Nothing else — the

host side is Python stdlib, so the system /usr/bin/python3 is enough and there is nothing to build.

• Claude Code, if you want the MCP tools. The bridge itself works without it.

Guest (System 7):

• System 7.5.3 or later with Open Transport (verified on 7.5.3, 7.6.1 and

Mac OS 9) or MacTCP — or no network stack at all, over a Serial line.

• 12 MB of RAM, which is what the installer's preflight checks for.
• A real Macintosh works too. Validated on a 68030 SE/30, where the link

runs over RS-422 serial rather than Ethernet — the transport is a seam, not an assumption (NET=Serial; see [docs/SERIALTRANSPORT.md](docs/SERIALTRANSPORT.md)). An emulator is the easy path, not the only one.

• No compiler, and no MPW. MPW + ToolServer are optional and add the

command tier (mpw_execute, mac_compile, mac_build). Without them everything else still works: screenshots, fork-aware file transfer, input injection, directory listings, clipboard, launch and shutdown. An absent ToolServer is a tier you do not have, not a broken install.

Three steps to a working bridge, then one command to confirm it: 1–2 on the host, 3 inside the emulator, 4 back on the host. The guest step cannot be scripted, because System 7 offers no scripting surface for the TCP/IP control panel.

Claude Code is not part of that. The bridge is a host server and a guest daemon; you drive it over the control port with anything that can open a socket. Step 5 wires it to Claude Code for those who want the MCP tools, and it is the only optional step here. Fully worked example with more screenshots: [docs/SETUP.md](docs/SETUP.md).

note: I simply gave Claude Code the URL of this GitHub and he did the complete install.\ But I don't know, if this applies to all of you, as my chap Claude was my co developer and might have READ.ME files, you are missing.\ Simply give it a try and tell us about your experience.

1. Configure the host

git clone https://github.com/LoetLuemmel/AppleBridge.git
cd AppleBridge/host
./install_bridge.py --dry-run   # read the plan; it changes nothing
./install_bridge.py

The clone is the whole download: the host side is Python stdlib, so there is nothing to build and no dependencies to fetch.

install_bridge.py then discovers your emulator, sets its Ethernet backend to slirp, writes host/local.env, installs the launchd agent that keeps the host server running, and prints the guest-side values you need in step 3 — labelled by whose address each one is, which is the mistake this step exists to prevent. It asks for nothing and needs no password.

What that costs, stated rather than buried: the slirp backend carries no AppleTalk. The Chooser stays empty, and mac_appletalk_browse, NBPLOOK and AFPMOUNT — all built and tested — cannot be exercised on the branch this installs. TCP keeps working either way, which is exactly how that gap disguises itself. AppleTalk lives on the hand-configured etherhelper branch, which needs two interactive password prompts per launch and therefore cannot start unattended; that trade is the reason slirp is what ships.

If it refuses, read what it says. It will not convert a host already configured for the etherhelper backend, because that is somebody's working AppleTalk setup — except on a machine with one network interface, where it says the opposite and means it: a bridged backend cannot reach the machine it runs inside, so no amount of hand-configuring that branch produces a bridge there. --force-slirp overrides either.

2. Get the guest kit

Download AppleBridgeKit.dmg from the [latest release](../../releases) — a 2 MB disk image holding the four 68K applications, the journaling driver the daemon opens by name, and a prefs file. Add it to the emulator as a second disk and relaunch, because the disk list is read at launch only:

disk /path/to/AppleBridgeKit.dmg

There is nothing to stamp on it. The prefs ship IP=10.0.2.2 — not the address of the machine that built the kit, which a public artifact must never carry, but the slirp constant that means whichever host runs the emulator: slirp forwards it to that host's loopback, and the server hears it there because it binds every address. So the kit needs no seeding step and no address of yours.

The exception is a bridge server running on a different machine than the emulator. Then the loopback is the wrong host, and only that machine's own address can say so — set it in AppleBridgeConfig on the guest afterwards, or write it into the image before you mount it:

cd host && ./install_bridge.py --seed-guest-prefs ~/Downloads/AppleBridgeKit.dmg

That second route needs hfsutils (brew install hfsutils), which macOS does not ship; the config panel on the guest needs nothing.

3. In the guest: network first, then the installer

TCP/IP control panel — these are the guest's own values, and slirp answers DHCP itself:

Connect via   Ethernet
Configure     Using DHCP Server

Do this before running the installer. Nothing breaks if you don't — the daemon redials every 30 seconds and picks itself up — but an installer reporting success over a bridge that never comes up reads like a failed install when only one field is wrong.

Then open the AppleBridge Kit volume and run AppleBridgeInstaller from it. It preflights the machine, refuses environments that cannot work, copies the suite, and installs the autostart so the bridge comes up on every boot.

It says what it found before it does anything, and it names its own version so a screenshot is answerable. A ? is not a failure — ToolServer is optional, and says so. If a required check fails, the Install button stays disabled rather than letting you start something that cannot finish.

Press Install, and it reports where everything went and offers Restart:

When it is done, drag the kit volume to the Trash and remove its disk line. On the first boot afterwards the daemon confirms it is running:

If it does not go to plan, the installer wrote down why. It leaves a text file called AppleBridge Install Log at the root of the guest's boot volume — the preflight table, the transports it found, one line per copied binary with its error code, and whatever the window said. It is written when the installer opens, before you press anything, so a run whose Install button is disabled by a failed check leaves a record too. Attach that file to an issue and the answer is usually in it. (The host installer does the same into ~/Library/Logs/AppleBridge/.)

The control panel

The daemon is faceless — it runs as a service with no window — so everything a human needs to change about it lives in AppleBridgeConfig, installed alongside it. Open it from the installation folder whenever you need to look:

| | | |---|---| | Daemon / Autostart | whether the service is running, and whether it starts at boot | | Host IP | the one value a kit cannot know — the host's address, not the guest's, which is the confusion the label exists to end. Set writes it and the daemon picks it up | | Networking service | Open Transport, MacTCP or Serial. NET= hot-swaps between commands, without relaunching the daemon | | Serial port / Baud | dimmed unless Serial is selected. Read at startup, not hot-swapped, so they take effect on th

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: LoetLuemmel
• Source: LoetLuemmel/AppleBridge
• License: MIT
• Homepage: https://td5.390er.de/applebridge/

Install and usage instructions live in the source repository linked above.