Amiga 模拟器 MCP 服务器

Amiberry MCP Server

An MCP (Model Context Protocol) server for Amiberry, the Amiga emulator. It lets an AI assistant list and edit configurations, launch games and disk images, control a running emulation, and debug Amiga code.

The server speaks plain MCP over stdio, so any MCP client can use it: Claude Desktop, Claude Code, Codex, Gemini (Antigravity), Cursor, Cline, Windsurf, and others. The installer configures Claude Desktop, Claude Code, Codex, and Gemini/Antigravity. For other clients, see Other MCP clients.

A separate HTTP API exposes the same functions as REST endpoints for scripts, home automation, and voice assistants.

Features

Files and launching

• List and launch Amiberry configurations, or launch a Quickstart model (A1000, A500, A500P, A600, A2000, A3000, A1200, A4000, CD32, CDTV)
• Search disk images (ADF, HDF, DMS, LHA, ISO, CUE, CHD) and launch WHDLoad games from LHA archives
• Launch CD32 and CDTV images, and set up the disk swapper for multi-disk games
• Parse, edit, and create .uae configuration files from model templates
• Read metadata from .uss savestates and identify Kickstart ROMs by checksum

Runtime control (needs Amiberry built with IPC support)

• Pause, resume, reset, frame-advance, save and load states
• Swap floppies, CDs, and WHDLoad games in a running emulation
• Change chipset, CPU, memory, display, sound, and input settings at runtime
• Send keystrokes, text, and mouse input
• Take screenshots and click, drag, or hover at pixels picked from a screenshot
• Control one of several running Amiberry instances

Debugging

• Launch with logging, tail logs, and wait for a log pattern
• Detect crashes from the process exit status and log contents; kill and restart
• Read and write emulated memory, inspect CPU and custom chip registers, disassemble, single-step, and set breakpoints
• Use the GDB monitor command set (watchpoints, conditions, task and segment lists) without a GDB client

Requirements

• Python 3.10 or newer
• Amiberry:
  • macOS: Amiberry.app in /Applications
  • Linux and FreeBSD: amiberry on PATH
  • Windows: installed by the Amiberry installer or Amiberry.exe on PATH. The server finds the installer's copy through its registry entry (per-user under %LOCALAPPDATA%\Programs\amiberry, all-users under %ProgramFiles%\amiberry) without any PATH setup.
• An MCP client

The server runs on Linux, FreeBSD, macOS, and Windows, and raises RuntimeError on any other platform.

Runtime control talks to Amiberry over IPC, which needs Amiberry built with USE_IPC_SOCKET=ON. That is the default on all four platforms since Windows gained the named-pipe transport after 8.4.1. On Windows the endpoint is the named pipe \\.\pipe\amiberry (further instances use \\.\pipe\amiberry_1 through \\.\pipe\amiberry_9). Elsewhere it is the Unix socket $XDG_RUNTIME_DIR/amiberry.sock, or /tmp/amiberry.sock when XDG_RUNTIME_DIR is unset.

Installation

Installer (macOS, Linux, FreeBSD)

git clone https://github.com/BlitterStudio/amiberry-mcp-server.git
cd amiberry-mcp-server
./scripts/install.sh

The installer:

1. Creates a virtual environment in venv/
2. Installs the package and its dependencies
3. Adds an amiberry entry to the Claude Desktop config, creating the file if needed
4. Adds the same entry for Claude Code, Codex, and Gemini (Antigravity) when it finds them installed

Other clients need the entry added by hand. See Other MCP clients.

Manual installation

The installer is a shell script and does not run on Windows. Install manually there, or on any platform where you prefer to:

python3 -m venv venv
source venv/bin/activate        # Windows: venv\Scripts\activate
pip install -e .                # or ".[http]" to include the HTTP API

Then add the server to your client as described below.

Client configuration

Every stdio MCP client needs the same command and arguments:

Claude Desktop

Edit the config file for your platform:

Add the server under mcpServers:

{
  "mcpServers": {
    "amiberry": {
      "command": "/path/to/amiberry-mcp-server/venv/bin/python",
      "args": ["-m", "amiberry_mcp.server"]
    }
  }
}

On Windows, escape the backslashes in the JSON path ("C:\\path\\to\\amiberry-mcp-server\\venv\\Scripts\\python.exe"). Restart Claude Desktop afterwards.

Other MCP clients

Add an entry with the same command and arguments:

Checking the setup

Restart the client. The Amiberry tools should appear in its tool list (the /mcp command, a tools icon, or a tool inspector, depending on the client). Then ask something like:

• "What Amiberry configurations do I have?"
• "Show me my disk images"
• "Launch Amiberry with the A500 model"

Amiberry directories

The server reads and writes the same directories Amiberry uses. It also creates a logs directory under the content root for logs it captures.

Inside the content root:

Amiberry/
├── Configurations/    # .uae config files
├── Floppies/          # .adf, .adz, .dms
├── HardDrives/        # .hdf, .hdz
├── LHA/               # .lha archives (WHDLoad games)
├── CDROMs/            # ISO, CUE, CHD
├── SaveStates/        # .uss savestates
├── Screenshots/
├── ROMs/              # Kickstart ROMs
└── logs/              # logs captured by this server

The settings directory holds settings only; it is not a second .uae config tree.

Overrides:

• AMIBERRY_BINARY points the server at a specific Amiberry executable, on any platform, ahead of the automatic discovery (PATH, the Windows installer's registry entry, and the default Windows install directories). Handy for a portable copy or a development build.
• AMIBERRY_HOME_DIR replaces the content root, unless portable mode is on.
• An amiberry.portable file next to the Amiberry binary switches Amiberry to portable mode, and the server follows that root. macOS ignores the marker.
• AMIBERRY_CONFIG_DIR replaces the configurations directory on Linux and FreeBSD. Windows does not honor it: configurations are always in <content root>\Configurations.

ROM, savestate, and disk listings also search the pre-8.4 directory names that Amiberry still migrates (kickstarts, roms, savestates, floppies, harddrives, lha, and their case variants), so files copied from an older tree still show up.

MCP tools

The server exposes 150 tools. Tools whose names start with runtime_ act on a running emulation over IPC; the rest work on files and processes.

Configurations and files

Launching

Processes, logs, and crashes

Runtime: emulation and state

Runtime: media

Runtime: hardware

Runtime: display and sound

Runtime: input

Runtime: screenshot-driven GUI automation

See Screenshot-driven GUI automation.

Runtime: debugging

Runtime: debugger monitor

MONITOR runs the GDB monitor command set without a GDB client. The typed tools below build the command, check the arguments, and parse the JSON reply. runtime_monitor sends one raw command string. The HTTP API exposes the raw command as POST /runtime/debug/monitor.

Read-only queries work while the guest runs, except guest RAM reads when cpu_threaded=true.

These actions change debugger state and need the emulation paused (PAUSE) or the native debugger stopped:

• watch add, range, remove, clear-events
• DMA watch add, remove
• condition add, remove
• exception mask
• history on, off
• guest output on, off, clear
• process break name, address, clear

A watch, condition, exception, or process-entry hit stops in the native debugger. runtime_debug_status then reports stopped=1 and a reason= (T05awatch:..., T05breakpoint:N;, T05winuae-exception:..., T05winuae-entry:...). DEBUG_CONTINUE resumes. The monitor refuses step-over, checkpoint, and input sequence.

Watch add and range take nine fields: address, size, access, source mask, value enabled, value, value mask, change-only, and log-only. Numbers are hexadecimal. Access is 1 for read, 2 for write, 3 for both; a range can also set bit 2 for instruction fetch. Change-only requires a write. An exact watch cannot include the CPU instruction source.

Instances and IPC

Screenshot-driven GUI automation

GUI actions use coordinates taken from a screenshot. Call runtime_screenshot_view, look at the returned image, and pass pixel coordinates from that exact image to runtime_gui_move, runtime_gui_click, or runtime_gui_drag. Every action also takes the returned capture_id and a request_id that the caller generates.

The screenshot metadata declares coordinate_space="screenshot_pixels", the image size, and a half-open actionable_bounds rectangle. Points must be integer pixels inside both the image and those bounds. The server translates them for scaling, HiDPI, viewport, and monitor layout; callers should not convert coordinates themselves.

request_id is 1-128 characters from A-Z, a-z, 0-9, ., _, :, and -. Retrying with the same ID and payload returns the original result with deduplicated=true. Reusing an ID with a different payload returns request_id_conflict. The server keeps only a bounded number of past results, so an ID deduplicates retries within that window, not forever.

Each action returns a versioned result with ok, code, message, controller_id, request_id, action, execution_state, failure_phase, next_action, retryable, recapture_required, cleanup_state, cleanup_context, deduplicated, and capture, runtime, and coordinate context. Follow next_action and recapture_required when recovering from a failure. cleanup_unconfirmed means the outcome is unknown: check what is on screen before deciding whether to repeat the action.

Captures and request IDs belong to one controller process. A capture stays valid only while its instance, runtime identity, monitor, and geometry revision still match; take a new screenshot whenever the result asks for one. Use either the MCP server or the HTTP server as the controller for a given Amiberry instance, not both at once.

Older Amiberry builds still return a screenshot, but the metadata has actionable=false, capture_id=null, and next_action="upgrade_runtime". Actionable captures need Amiberry's SDL or OpenGL renderer. The Vulkan renderer returns plain screenshots and rejects GUI actions, because it cannot yet tie screenshot pixels to the geometry of the presented frame. There is no fallback to relative coordinates. GUI automation is supported on Linux, macOS, and Windows. The Windows named-pipe path was validated live against an installed Amiberry build: actionable capture, the guarded configuration compare-and-set, clicks, drags, and stale-capture rejection after a window resize and after a restart all behaved as specified, with held buttons read back from the emulated CIA registers. Automated tests cover the action contract and coordinate geometry; each release is also checked against a live Amiberry separately.

Example prompts

Library and launching

• "List my Amiberry configurations"
• "Find disk images containing 'Shadow of the Beast'"
• "Launch Amiberry with the A1200 model"
• "Launch the WHDLoad game 'Turrican'"
• "Launch the CD32 game from /path/to/game.iso"
• "Create a new A1200 config with 8MB Fast RAM"
• "What CPU and chipset does my savestate use?"

Running emulation

• "Pause the emulation" / "Take a screenshot"
• "Quick save to slot 0"
• "Insert disk 2 into drive DF0"
• "Set the floppy speed to 800" / "Enable warp mode"
• "Switch to the AGA chipset and a 68030 CPU"
• "Set Chip RAM to 2MB"
• "Type 'dir' and press Return"

Debugging

• "Launch Amiberry with logging enabled and show me the log"
• "Activate the debugger and show me the CPU registers"
• "Disassemble at 0xFC0000"
• "Set a breakpoint at 0x400 and continue"
• "Get the Copper and Blitter state"

HTTP API

The HTTP server (FastAPI) exposes the same functions as REST endpoints for scripts, home automation, and voice assistants such as Siri Shortcuts.

./scripts/install_http_api.sh   # install the HTTP dependencies
./scripts/start_http_api.sh     # start the server

The API listens on http://localhost:8080; interactive docs are at http://localhost:8080/docs. docs/HTTP_API_GUIDE.md has request formats, curl examples for every endpoint, and voice assistant setup. docs/QUICKSTART_HTTP_API.md is a short reference.

A few examples:

# Launch a model, list configs, stop Amiberry
curl -X POST http://localhost:8080/quick-launch/A500
curl http://localhost:8080/configs
curl -X POST http://localhost:8080/stop

# Launch a WHDLoad game
curl -X POST "http://localhost:8080/launch-whdload?search=Turrican"

# Control a running emulation
curl -X POST http://localhost:8080/runtime/pause
curl -X POST http://localhost:8080/runtime/insert-floppy \
  -H "Content-Type: application/json" \
  -d '{"drive": 0, "image_path": "/path/to/disk2.adf"}'
curl -X POST http://localhost:8080/runtime/type \
  -H "Content-Type: application/json" \
  -d '{"text": "dir\n", "delay_ms": 50}'

# Debugger
curl -X POST http://localhost:8080/runtime/breakpoints \
  -H "Content-Type: application/json" \
  -d '{"address": "0x400", "slot": 2}'
curl http://localhost:8080/runtime/cpu/regs

Endpoints

Endpoints under /runtime need a running Amiberry with IPC support.

Library, launching, and processes

Runtime: emulation and state

Runtime: media

Runtime: hardware

Memory changes take effect after a reset.

Runtime: display and sound

Runtime: input and GUI automation

Runtime: debugging

Runtime: instances and IPC

Starting at login

install_http_api.sh creates a LaunchAgent on macOS and a systemd user unit on Linux. Enable them with:

# macOS
launchctl load ~/Library/LaunchAgents/com.amiberry.httpapi.plist

# Linux
systemctl --user enable --now amiberry-http-api.service

Troubleshooting

The tools do not appear in the client

• Quit and reopen the client. Most clients load MCP servers only at startup.
• Check that the command path points at this project's venv/bin/python (venv\Scripts\python.exe on Windows) and that the file exists.
• Run python -m amiberry_mcp.server from the virtual environment. It should wait silently for input on stdin; if it prints an error, fix that first.
• Read the client's MCP log:
  • Claude Desktop (macOS): ~/Library/Logs/Claude/mcp*.log
  • Claude Code: claude mcp list, then check the server's stderr
  • Cursor: View → Output → "MCP" channel

"Command not found" when launching

• Linux and FreeBSD: put amiberry on PATH
• macOS: install Amiberry.app in /Applications
• Windows: install Amiberry with its installer, or put Amiberry.exe on PATH. The server checks PATH first, then the installer's registry entry (HKCU, then HKLM), then %LOCALAPPDATA%\Programs\amiberry\Amiberry.exe and %ProgramFiles%\amiberry\Amiberry.exe. Set AMIBERRY_BINARY to point at any other copy, such as a portable one.

Permission errors running the scripts

Make them executable: chmod +x scripts/*.sh

Where captured logs go

The logs directory under the content root: ~/Documents/Amiberry/logs on macOS, ~/Amiberry/logs on Linux and FreeBSD, %USERPROFILE%\Amiberry\logs on Windows.

Runtime control does not work

• Check that Amiberry is running and was built with USE_IPC_SOCKET=ON (a CMake option).
• On Linux, FreeBSD, and macOS, check that the socket exists: ls "${XDG_RUNTIME_DIR:-/tmp}/amiberry.sock". Test it directly with echo "GET_STATUS" | nc -U "${XDG_RUNTIME_DIR:-/tmp}/amiberry.sock".
• With several instances running, instance 0 uses amiberry.sock and the others use amiberry_1.sock, amiberry_2.sock, and so on up to instance 9. Pick one with set_active_instance.
• On Windows, list the pipes with Get-ChildItem \\.\pipe\ | Where-Object Name -like 'amiberry*'. Do not use Test-Path: it opens a client connection to the pipe.
• The Windows pipe transport needs asyncio's Proactor event loop, which is the default on Windows. If a dependency switches to a selector loop, the server reports an error saying so.

Development

git clone https://github.com/BlitterStudio/amiberry-mcp-server.git
cd amiberry-mcp-server
python3 -m venv venv
source venv/bin/activate
pip install -e ".[all]"         # HTTP, D-Bus, and dev dependencies

pytest tests/ -v                # run the tests
ruff check src/ tests/          # lint
ruff format src/ tests/         # format

Project layout:

amiberry-mcp-server/
├── src/amiberry_mcp/
│   ├── config.py          # platform detection and paths
│   ├── common.py          # shared helpers (launch, scan, validation)
│   ├── shared_state.py    # process state, IPC client caching, launch helpers
│   ├── server.py          # MCP server (150 tools)
│   ├── http_server.py     # HTTP API (FastAPI)
│   ├── ipc_client.py      # IPC client (Unix socket, named pipe, D-Bus)
│   ├── monitor.py         # MONITOR command builders and reply parsing
│   ├── gui_automation.py  # screenshot capture registry and GUI actions
│   ├── uae_config.py      # .uae parser and generator
│   ├── savestate.py       # .uss metadata parser
│   └── rom_manager.py     # ROM identification
├── scripts/               # install, uninstall, and HTTP API scripts
├── tests/                 # pytest suite, one file per module
├── docs/                  # HTTP API guide and quick reference
└── AGENTS.md              # architecture and code conventions

Uninstall

./scripts/uninstall.sh

Contributing

Issues and pull requests are welcome. AGENTS.md describes the architecture and code conventions: ruff settings, type annotations, error handling, and test layout.

License

GPL-3.0. See LICENSE.

Links

• Model Context Protocol
• Amiberry
• FastAPI
• MCP clients: Claude Desktop, Claude Code, Codex, Cursor, Cline, Continue, Windsurf