Amiberry

FreeNot checked

An MCP server for the Amiberry emulator

About

An MCP server for the Amiberry emulator

README

An MCP (Model Context Protocol) server for controlling Amiberry, the Amiga emulator, from any MCP-compatible AI assistant — Claude Desktop, Claude Code, Codex, Gemini (Antigravity), Cursor, Cline, Windsurf, and others.

MCP is client-agnostic. This README uses Claude Desktop as the worked example because its config path is well-known, but the server itself talks plain MCP over stdio and works with anything that speaks the protocol. The installer auto-configures Claude Desktop, Claude Code, Codex, and Gemini/Antigravity if it detects them; for other clients, point them at the same python -m amiberry_mcp.server command (see Other MCP clients below).

Features

Core Features

Browse and launch Amiberry configurations
Search for disk images (ADF, HDF, DMS, LHA, ISO, CUE, CHD)
List and manage savestates
View and edit configuration file contents
Launch emulator with specific models (A500, A500P, A600, A1200, A4000, CD32, CDTV)
HTTP API for voice assistants (Siri, Google Assistant) and automation

Runtime Control

Pause/Resume: Control running emulation via IPC
Save/Load State: Save and restore states while running
Disk Swapping: Insert floppy/CD images into running emulation
Live Configuration: Query and modify config options at runtime
Screenshots: Capture screenshots from running emulation
Screenshot-driven GUI Automation: Move, click, double-click, and drag safely using pixels from an exact screenshot
Keyboard Input: Send key presses or type text into the emulation
Multi-instance: Target a specific Amiberry instance when several are running
Cross-platform: Works on Linux and macOS

Developer/Debug Features

Log Capture: Launch with logging enabled and capture output to files
Log Tailing: Incremental log reading and pattern-based waiting
Crash Detection: Automatic crash detection via process signals and log scanning
Config Editor: Parse, modify, and create .uae configuration files
Savestate Inspector: Read metadata from .uss savestate files
ROM Manager: Identify and catalog Kickstart ROMs by checksum
Memory Access: Read/write emulated Amiga memory for debugging

Autonomous Troubleshooting

Process Lifecycle: Track, monitor, kill, and restart Amiberry processes
Health Check: Combined process + IPC + emulation status check
Launch and Wait: Launch Amiberry and wait until IPC is ready for commands
Screenshot Analysis: Capture screenshots with image data returned for AI analysis
Crash Recovery: Detect crashes, analyze logs, restart automatically

Game Launcher Features

WHDLoad Launcher: Search and launch WHDLoad games from LHA archives
CD Image Launcher: Launch CD32/CDTV games with auto-detection
Multi-Disk Support: Configure disk swapper for multi-disk games
Config Templates: Generate configs from pre-made model templates

Requirements

Python 3.10 or higher
Amiberry emulator installed:
- macOS: Amiberry.app in /Applications
- Linux: amiberry command in PATH
An MCP-compatible AI client (Claude Desktop, Claude Code, Codex, Gemini/Antigravity, Cursor, Cline, Windsurf, …)

Only macOS and Linux are supported — the server raises RuntimeError on other platforms. Runtime control additionally needs Amiberry built with USE_IPC_SOCKET=ON.

Project Structure

amiberry-mcp-server/
├── src/
│   └── amiberry_mcp/
│       ├── __init__.py
│       ├── 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 (133 tools, data-driven dispatch)
│       ├── http_server.py     # HTTP API server (FastAPI)
│       ├── ipc_client.py      # IPC client with persistent connections
│       ├── gui_automation.py  # Screenshot capture registry and GUI action service
│       ├── uae_config.py      # Config file parser/generator
│       ├── savestate.py       # Savestate metadata parser
│       └── rom_manager.py     # ROM identification
├── scripts/
│   ├── install.sh             # MCP server installer
│   ├── install_http_api.sh    # HTTP API installer
│   ├── start_http_api.sh      # HTTP API launcher
│   ├── uninstall.sh           # Uninstaller
│   └── test_http_api.sh       # HTTP API tests
├── tests/                     # pytest suite, one test file per module
├── docs/
│   ├── HTTP_API_GUIDE.md      # HTTP API documentation
│   └── QUICKSTART_HTTP_API.md # HTTP API quick reference
├── AGENTS.md                  # Architecture and code conventions
├── pyproject.toml
├── README.md
└── LICENSE

Installation

Quick Install (Recommended)

# Clone the repository
git clone https://github.com/BlitterStudio/amiberry-mcp-server.git
cd amiberry-mcp-server

# Run the installer
./scripts/install.sh

The installer will:

Create a Python virtual environment
Install dependencies
Auto-detect and configure any of: Claude Desktop, Claude Code, Codex, Gemini (Antigravity)

Other MCP clients (Cursor, Cline, Windsurf, …) aren't auto-configured — see Other MCP clients for the snippet to paste into their config.

Manual Installation

# Create and activate virtual environment
python3 -m venv venv
source venv/bin/activate

# Install the package
pip install -e .

# Configure your MCP client manually (see below)

Client Configuration

All MCP clients ultimately need the same two things: the command to launch and its args. For this server:

Field	Value
Command	`/path/to/amiberry-mcp-server/venv/bin/python`
Args	`["-m", "amiberry_mcp.server"]`
Transport	stdio

Claude Desktop

Edit your Claude Desktop configuration file:

macOS:

nano ~/Library/Application\ Support/Claude/claude_desktop_config.json

Linux:

nano ~/.config/Claude/claude_desktop_config.json

Add this configuration:

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

Then restart Claude Desktop.

Other MCP clients

The same command / args pair works for any stdio MCP client. Paste an equivalent entry into:

Claude Code — ~/.claude.json (the installer handles this automatically)
Codex — ~/.codex/config.toml, as a [mcp_servers.amiberry] block (installer handles this)
Gemini / Antigravity — ~/.gemini/antigravity/mcp_config.json (installer handles this)
Cursor — ~/.cursor/mcp.json (or .cursor/mcp.json inside a project)
Cline / Continue / Windsurf — see each client's MCP settings UI; same command/args
Anything else MCP-aware — point it at python -m amiberry_mcp.server via stdio

Verification

After installation, restart your AI client. You should see the Amiberry MCP tools become available (typically shown as a tool/hammer icon, in a /mcp list, or in the client's tool inspector).

Try asking your assistant:

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

Default Directory Structure

macOS

~/Documents/Amiberry/
├── Configurations/    # .uae config files
├── Floppies/         # .adf, .adz, .dms files
├── Harddrives/       # .hdf, .hdz files
├── Lha/              # .lha archives (WHDLoad games)
├── Savestates/       # .uss savestate files
├── Screenshots/
├── Kickstarts/       # Kickstart ROM files
└── logs/             # Captured log files

Linux

~/Amiberry/
├── conf/             # .uae config files
├── floppies/         # .adf, .adz, .dms files
├── harddrives/       # .hdf, .hdz files
├── lha/              # .lha archives (WHDLoad games)
├── savestates/       # .uss savestate files
├── screenshots/
├── kickstarts/       # Kickstart ROM files
└── logs/             # Captured log files

~/.config/amiberry/   # System configs (optional)

Set AMIBERRY_HOME_DIR to point the server at a different Amiberry home; every path above is derived from it. On Linux, XDG_CONFIG_HOME (default ~/.config) determines where the system config directory is looked up.

Available MCP Tools

The server exposes 133 tools. Names starting with runtime_ act on a running emulation over IPC; the rest work on files and processes.

Core Tools

Tool	Description
`list_configs`	List available configuration files
`get_config_content`	View contents of a config file
`list_disk_images`	Search for disk images (ADF/HDF/DMS/LHA)
`launch_amiberry`	Launch with config, model, disk, or LHA file
`list_savestates`	List available savestate files
`get_platform_info`	Show platform and path information

Configuration Tools

Tool	Description
`parse_config`	Parse .uae config file into structured data
`modify_config`	Change specific options in a config file
`create_config`	Generate new config from template

Launch Tools

Tool	Description
`launch_with_logging`	Launch with --log flag and capture output
`launch_whdload`	Search and launch WHDLoad games
`launch_cd`	Launch CD images (ISO/CUE/CHD)
`set_disk_swapper`	Configure multi-disk game support

Media Tools

Tool	Description
`list_cd_images`	List available CD images
`list_logs`	List captured log files
`get_log_content`	Read a captured log file

Analysis Tools

Tool	Description
`inspect_savestate`	Read metadata from .uss savestate files
`list_roms`	List available ROMs with identification
`identify_rom`	Get ROM details by checksum
`get_amiberry_version`	Get Amiberry version info

Runtime Control Tools

Emulation Control

Tool	Description
`pause_emulation`	Pause a running emulation
`resume_emulation`	Resume a paused emulation
`reset_emulation`	Soft or hard reset
`runtime_frame_advance`	Advance N frames when paused

Media Control

Tool	Description
`runtime_insert_floppy`	Insert floppy disk into drive
`runtime_eject_floppy`	Eject floppy from drive
`runtime_list_floppies`	List all floppy drives and contents
`runtime_insert_cd`	Insert CD image
`runtime_eject_cd`	Eject CD

State Management

Tool	Description
`runtime_screenshot`	Take a screenshot
`runtime_save_state`	Save state while running
`runtime_load_state`	Load a savestate
`runtime_quicksave`	Quick save to slot (0-9)
`runtime_quickload`	Quick load from slot (0-9)

Audio Control

Tool	Description
`runtime_set_volume`	Set master volume (0-100)
`runtime_get_volume`	Get current volume
`runtime_mute`	Mute audio
`runtime_unmute`	Unmute audio

Display Control

Tool	Description
`runtime_toggle_fullscreen`	Toggle fullscreen/windowed mode
`runtime_set_warp`	Enable/disable warp mode
`runtime_get_warp`	Get warp mode status
`runtime_set_display_mode`	Set mode (0=window, 1=fullscreen, 2=fullwindow)
`runtime_get_display_mode`	Get current display mode
`runtime_set_ntsc`	Set video mode (0=PAL, 1=NTSC)
`runtime_get_ntsc`	Get current video mode (PAL/NTSC)

Sound Control

Tool	Description
`runtime_set_sound_mode`	Set mode (0=off, 1=normal, 2=stereo, 3=best)
`runtime_get_sound_mode`	Get current sound mode

Joystick/Input Control

Tool	Description
`runtime_get_joyport_mode`	Get port mode (0-3)
`runtime_set_joyport_mode`	Set port mode (0=default, 2=mouse, 3=joy, 7=cd32)
`runtime_get_autofire`	Get autofire mode for port
`runtime_set_autofire`	Set autofire (0=off, 1=normal, 2=toggle, 3=always, 4=toggle_noaf)

Floppy Control

Tool	Description
`runtime_set_floppy_speed`	Set floppy speed (0=turbo, 100=1x, 200=2x, 400=4x, 800=8x)
`runtime_get_floppy_speed`	Get current floppy speed
`runtime_disk_write_protect`	Set disk write protection for drive
`runtime_get_disk_write_protect`	Get disk write protection status

Display Control (additional)

Tool	Description
`runtime_toggle_rtg`	Toggle between RTG and chipset display
`runtime_toggle_status_line`	Cycle status line (off/chipset/rtg/both)
`runtime_get_fps`	Get current frame rate and idle percentage

Input Control (additional)

Tool	Description
`runtime_toggle_mouse_grab`	Toggle mouse capture/grab
`runtime_get_mouse_speed`	Get current mouse sensitivity

Hardware/Chipset Control

Tool	Description
`runtime_set_chipset`	Set chipset (OCS, ECS_AGNUS, ECS_DENISE, ECS, AGA)
`runtime_get_chipset`	Get current chipset
`runtime_set_cpu_speed`	Set CPU speed (-1=max, 0=cycle-exact, >0=%)
`runtime_get_cpu_speed`	Get current CPU speed setting
`runtime_get_memory_config`	Get all memory sizes (chip, fast, bogo, z3, rtg)

Memory Configuration

Tool	Description
`runtime_set_chip_mem`	Set Chip RAM size (256, 512, 1024, 2048, 4096, 8192 KB)
`runtime_set_fast_mem`	Set Fast RAM size (0, 1024, 2048, 4096, 8192 KB)
`runtime_set_slow_mem`	Set Slow/Bogo RAM size (0, 256, 512, 1024, 1792 KB)
`runtime_set_z3_mem`	Set Zorro III RAM size (0, 1, 2, 4, 8, 16, 32, 64, 128, 256, 512, 1024 MB)
`runtime_get_cpu_model`	Get current CPU model (68000, 68010, 68020, 68030, 68040, 68060)
`runtime_set_cpu_model`	Set CPU model

Window/Display Control

Tool	Description
`runtime_set_window_size`	Set emulator window size (width x height)
`runtime_get_window_size`	Get current window dimensions
`runtime_set_scaling`	Set scaling mode (-1=auto, 0=nearest, 1=linear, 2=integer)
`runtime_get_scaling`	Get current scaling mode
`runtime_set_line_mode`	Set line mode (single, double, scanlines)
`runtime_get_line_mode`	Get current line mode
`runtime_set_resolution`	Set display resolution (lores, hires, superhires)
`runtime_get_resolution`	Get current resolution mode
`runtime_set_autocrop`	Enable/disable automatic display cropping
`runtime_get_autocrop`	Get current autocrop status

WHDLoad Control

Tool	Description
`runtime_insert_whdload`	Load a WHDLoad game (LHA archive or directory)
`runtime_eject_whdload`	Eject the currently loaded WHDLoad game
`runtime_get_whdload`	Get info about currently loaded WHDLoad game

Instance Control

Tool	Description
`get_active_instance`	Get the currently active Amiberry instance being controlled
`set_active_instance`	Set the active instance to control (e.g. 0, 1, 2; `null` to auto-discover)

Debugging and Diagnostics

Tool	Description
`runtime_debug_activate`	Activate the built-in debugger
`runtime_debug_deactivate`	Deactivate debugger and resume emulation
`runtime_debug_status`	Get debugger status (active/inactive)
`runtime_debug_step`	Single-step CPU instructions
`runtime_debug_continue`	Continue execution until next breakpoint
`runtime_get_cpu_regs`	Get all CPU registers (D0-D7, A0-A7, PC, SR, USP, ISP)
`runtime_get_custom_regs`	Get custom chip registers (DMACON, INTENA, INTREQ, etc.)
`runtime_disassemble`	Disassemble instructions at a memory address
`runtime_set_breakpoint`	Set a breakpoint at a memory address
`runtime_clear_breakpoint`	Clear a breakpoint or all breakpoints
`runtime_list_breakpoints`	List all active breakpoints
`runtime_get_copper_state`	Get Copper coprocessor state
`runtime_get_blitter_state`	Get Blitter state (busy, channels, dimensions)
`runtime_get_drive_state`	Get floppy drive state (track, side, motor)
`runtime_get_audio_state`	Get audio channel states
`runtime_get_dma_state`	Get DMA channel states

Status

Tool	Description
`runtime_get_led_status`	Get all LED states (power, floppy, HD, CD)
`runtime_list_harddrives`	List mounted hard drives/directories

Configuration

Tool	Description
`get_runtime_status`	Get emulation status
`runtime_get_config`	Get config option value
`runtime_set_config`	Set config option
`runtime_list_configs`	List config files known to the running emulator

Input Control

Tool	Description
`runtime_send_key`	Send keyboard input by key name (e.g. 'space', 'return', 'f1') or scancode, with press/release/press-and-release
`runtime_send_text`	Send a string of text into the emulation (handles shift for uppercase/symbols)
`runtime_send_mouse`	Send mouse movement and buttons
`runtime_set_mouse_speed`	Set mouse sensitivity (10-200)

Utility

Tool	Description
`runtime_get_version`	Get Amiberry and SDL version info
`runtime_ping`	Test IPC connection (returns PONG)
`check_ipc_connection`	Check IPC availability

Process Lifecycle Management

Tool	Description
`check_process_alive`	Check if Amiberry process is running (PID, exit code, signal)
`get_process_info`	Detailed process info with crash detection
`kill_amiberry`	Force kill a running/hung Amiberry process
`wait_for_exit`	Wait for process to exit with configurable timeout
`restart_amiberry`	Kill and re-launch with same command

Memory Access

Tool	Description
`runtime_read_memory`	Read emulated Amiga memory (1/2/4 bytes)
`runtime_write_memory`	Write emulated Amiga memory (1/2/4 bytes)

Runtime Configuration

Tool	Description
`runtime_load_config`	Load a .uae config file into running emulation
`runtime_debug_step_over`	Step over subroutine calls (JSR/BSR)

Screenshot Analysis

Tool	Description
`runtime_screenshot_view`	Return exact image data plus actionable capture metadata
`runtime_gui_move`	Move or hover at a pixel from that capture
`runtime_gui_click`	Click or double-click a named button at a captured pixel
`runtime_gui_drag`	Drag a named button between two captured pixels

Log Tailing & Crash Detection

Tool	Description
`tail_log`	Get new log lines since last read (incremental)
`wait_for_log_pattern`	Wait for a regex pattern in log output
`get_crash_info`	Detect crashes via process state and log scanning

Workflow Automation

Tool	Description
`health_check`	Combined check: process + IPC + emulation status + FPS
`launch_and_wait_for_ipc`	Launch Amiberry and wait until IPC socket is ready

Note: Runtime control requires Amiberry built with USE_IPC_SOCKET=ON

Screenshot-driven GUI automation

GUI automation is screenshot-first. Call runtime_screenshot_view, inspect the returned image, and use pixel coordinates from that exact image in one of runtime_gui_move, runtime_gui_click, or runtime_gui_drag. Pass the returned capture_id and a caller-generated request_id with every action.

The screenshot metadata declares coordinate_space="screenshot_pixels", the image dimensions, and a half-open actionable_bounds rectangle. Points must be integer screenshot pixels inside both the image and those bounds. The service performs scaling, HiDPI, viewport, and monitor translation; callers should not convert coordinates themselves.

Tool	Required fields	Optional fields
`runtime_gui_move`	`capture_id`, `request_id`, `x`, `y`	`dwell_ms` (default `0`, range `0..5000`)
`runtime_gui_click`	`capture_id`, `request_id`, `x`, `y`	`button` (`left`, `right`, or `middle`; default `left`), `click_count` (`1` or `2`; default `1`)
`runtime_gui_drag`	`capture_id`, `request_id`, `start_x`, `start_y`, `end_x`, `end_y`	`button` (`left`, `right`, or `middle`; default `left`)

request_id must be 1-128 characters from A-Z, a-z, 0-9, ., _, :, or -. An identical retained retry returns the original result with deduplicated=true; reusing the same ID with a changed payload returns request_id_conflict. Retention is bounded, so an ID is an idempotency key for the controller's retained window, not a permanent global record.

Every 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/coordinate context. Treat next_action and recapture_required as mandatory recovery guidance. In particular, cleanup_unconfirmed means the action outcome is unknown: reconcile the visible state and do not blindly replay it.

capture_id and request_id state belong to one controller process. A capture can only be reused while its selected instance, runtime identity, monitor, and geometry revision still match; recapture whenever directed. Run either the MCP server or the HTTP server as the controller for a given Amiberry instance. Simultaneous MCP and HTTP controller processes for the same runtime instance are unsupported.

Older Amiberry builds can still return a visible screenshot, but its metadata has actionable=false, capture_id=null, and next_action="upgrade_runtime". Actionable capture currently requires Amiberry's SDL or OpenGL renderer; Vulkan continues to support legacy screenshots but rejects coordinate automation until it can pair screenshot pixels with the exact presented frame geometry. There is deliberately no relative-coordinate fallback. Actionable GUI automation is supported on Linux and macOS; live platform validation remains a separate release check from the automated contract and geometry tests.

Usage Examples

Basic Usage

Ask your AI assistant:

"List my Amiberry configurations"
"Show me all Workbench disk images"
"Launch Amiberry with the A1200 model"
"What savestates do I have?"
"Find disk images containing 'Shadow of the Beast'"

WHDLoad Games

"Launch the WHDLoad game 'Turrican'"
"Search for WHDLoad games with 'Adventure' in the name"

CD32/CDTV Games

"List my CD images"
"Launch the CD32 game from /path/to/game.iso"

Configuration Management

"Parse my A500 config file and show the memory settings"
"Create a new A1200 config with 8MB Fast RAM"
"Change the floppy speed to 800 in my gaming config"

Debugging

"Launch Amiberry with logging enabled"
"Show me the last captured log file"
"What ROMs do I have available?"
"Inspect my savestate from yesterday"

Savestate Analysis

"What CPU and chipset is my savestate using?"
"Show me metadata from my Shadow of the Beast savestate"

Runtime Control

"Pause the emulation"
"Take a screenshot of the current state"
"Save the game state to checkpoint.uss"
"Quick save to slot 0"
"Quick load from slot 1"
"Insert disk 2 into drive DF0"
"Eject the floppy from drive 0"
"List what's in all the floppy drives"
"List mounted hard drives"
"What's the current emulation status?"
"Set the floppy speed to 800"
"Set the volume to 50%"
"Mute the audio"
"Toggle fullscreen mode"
"Enable warp mode"
"Switch to NTSC mode"
"Set display to fullscreen mode"
"Set sound mode to stereo"
"Get joystick port 0 mode"
"Set port 0 to joystick mode"
"Enable autofire on port 0"
"Get LED status"
"Advance one frame"
"What version of Amiberry is running?"
"Ping Amiberry to check the connection"
"Set floppy speed to maximum"
"What's the current FPS?"
"Toggle RTG display"
"Switch to AGA chipset"
"What's the CPU speed?"
"Set CPU to maximum speed"
"Show me the memory configuration"
"Toggle mouse grab"
"Protect disk in drive 0"
"Set Chip RAM to 2MB"
"Set Fast RAM to 8MB"
"What CPU model is being used?"
"Switch to 68030 CPU"
"Set window size to 800x600"
"Set scaling mode to linear"
"Set line mode to scanlines"
"Switch to hires resolution"
"Enable autocrop"
"Is autocrop enabled?"
"Load the Turrican WHDLoad game"
"What WHDLoad game is loaded?"
"Eject the WHDLoad game"

Keyboard Input

"Press the space bar"
"Type 'dir' and press Return"
"Press F1"
"Press Escape"
"Hold Ctrl and press C"
"Type 'list' followed by Enter"

Debugging and Diagnostics

"Activate the debugger"
"What's the debugger status?"
"Single-step 10 instructions"
"Continue execution"
"Deactivate the debugger"
"Show me the CPU registers"
"Disassemble at address 0xFC0000"
"Get the custom chip registers"
"Set a breakpoint at 0x400"
"List all breakpoints"
"Clear the breakpoint at 0x400"
"Clear all breakpoints"
"Get the Copper state"
"Get the Blitter state"
"Get floppy drive 0 state"
"Get audio channel states"
"Get DMA state"

HTTP API

Control Amiberry via REST API for voice assistants and automation.

Quick Start

# Install HTTP API dependencies
./scripts/install_http_api.sh

# Start the server
./scripts/start_http_api.sh

The API runs on http://localhost:8080. View documentation at http://localhost:8080/docs.

Example Commands

Siri/Voice:

"Hey Siri, launch Amiga 500"
"Hey Siri, stop Amiberry"

curl:

# Basic operations
curl -X POST http://localhost:8080/quick-launch/A500
curl -X POST http://localhost:8080/stop
curl http://localhost:8080/configs

# Launch with logging
curl -X POST http://localhost:8080/launch-with-logging \
  -H "Content-Type: application/json" \
  -d '{"model": "A500"}'

# Create a config
curl -X POST "http://localhost:8080/configs/create/my-config?model=A1200"

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

# Launch CD image
curl -X POST http://localhost:8080/launch-cd \
  -H "Content-Type: application/json" \
  -d '{"cd_path": "/path/to/game.iso"}'

# Inspect savestate
curl http://localhost:8080/savestates/mysave.uss/inspect

# List ROMs, or identify one by path (must be inside the Amiberry home directory)
curl http://localhost:8080/roms
curl "http://localhost:8080/roms/identify?rom_path=$HOME/Amiberry/kickstarts/kick13.rom"

# Runtime control (requires Amiberry with USE_IPC_SOCKET=ON)
curl http://localhost:8080/runtime/status
curl -X POST http://localhost:8080/runtime/pause
curl -X POST http://localhost:8080/runtime/resume
curl -X POST http://localhost:8080/runtime/screenshot \
  -H "Content-Type: application/json" \
  -d '{"filename": "/tmp/screenshot.png"}'
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/eject-floppy \
  -H "Content-Type: application/json" \
  -d '{"drive": 0}'
curl http://localhost:8080/runtime/list-floppies

# Audio control
curl http://localhost:8080/runtime/volume
curl -X POST http://localhost:8080/runtime/volume \
  -H "Content-Type: application/json" \
  -d '{"volume": 50}'
curl -X POST http://localhost:8080/runtime/mute
curl -X POST http://localhost:8080/runtime/unmute

# Display control
curl -X POST http://localhost:8080/runtime/fullscreen
curl http://localhost:8080/runtime/warp
curl -X POST http://localhost:8080/runtime/warp \
  -H "Content-Type: application/json" \
  -d '{"enabled": true}'

# Display mode (0=window, 1=fullscreen, 2=fullwindow)
curl http://localhost:8080/runtime/display-mode
curl -X POST http://localhost:8080/runtime/display-mode \
  -H "Content-Type: application/json" \
  -d '{"mode": 1}'

# Video mode (PAL/NTSC)
curl http://localhost:8080/runtime/ntsc
curl -X POST http://localhost:8080/runtime/ntsc \
  -H "Content-Type: application/json" \
  -d '{"enabled": true}'

# Sound mode (0=off, 1=normal, 2=stereo, 3=best)
curl http://localhost:8080/runtime/sound-mode
curl -X POST http://localhost:8080/runtime/sound-mode \
  -H "Content-Type: application/json" \
  -d '{"mode": 2}'

# Quick save/load (slots 0-9)
curl -X POST http://localhost:8080/runtime/quicksave \
  -H "Content-Type: application/json" \
  -d '{"slot": 0}'
curl -X POST http://localhost:8080/runtime/quickload \
  -H "Content-Type: application/json" \
  -d '{"slot": 0}'

# Joystick port control (port 0-3, mode: 0=default, 2=mouse, 3=joy, 7=cd32)
curl http://localhost:8080/runtime/joyport/0
curl -X POST http://localhost:8080/runtime/joyport \
  -H "Content-Type: application/json" \
  -d '{"port": 0, "mode": 3}'

# Autofire control (0=off, 1=normal, 2=toggle, 3=always, 4=toggle_noaf)
curl http://localhost:8080/runtime/autofire/0
curl -X POST http://localhost:8080/runtime/autofire \
  -H "Content-Type: application/json" \
  -d '{"port": 0, "mode": 1}'

# Status
curl http://localhost:8080/runtime/led-status
curl http://localhost:8080/runtime/harddrives

# Floppy speed control
curl http://localhost:8080/runtime/floppy-speed
curl -X POST http://localhost:8080/runtime/floppy-speed \
  -H "Content-Type: application/json" \
  -d '{"speed": 800}'

# Disk write protection
curl http://localhost:8080/runtime/disk-write-protect/0
curl -X POST http://localhost:8080/runtime/disk-write-protect \
  -H "Content-Type: application/json" \
  -d '{"drive": 0, "protected": true}'

# RTG and status line
curl -X POST http://localhost:8080/runtime/rtg
curl -X POST http://localhost:8080/runtime/status-line

# FPS monitoring
curl http://localhost:8080/runtime/fps

# Mouse grab
curl -X POST http://localhost:8080/runtime/mouse-grab
curl http://localhost:8080/runtime/mouse-speed

# Chipset control
curl http://localhost:8080/runtime/chipset
curl -X POST http://localhost:8080/runtime/chipset \
  -H "Content-Type: application/json" \
  -d '{"chipset": "AGA"}'

# CPU speed
curl http://localhost:8080/runtime/cpu-speed
curl -X POST http://localhost:8080/runtime/cpu-speed \
  -H "Content-Type: application/json" \
  -d '{"speed": -1}'

# Memory configuration
curl http://localhost:8080/runtime/memory-config

# Memory management (changes require reset)
curl -X POST http://localhost:8080/runtime/chip-mem \
  -H "Content-Type: application/json" \
  -d '{"size_kb": 2048}'
curl -X POST http://localhost:8080/runtime/fast-mem \
  -H "Content-Type: application/json" \
  -d '{"size_kb": 8192}'
curl -X POST http://localhost:8080/runtime/slow-mem \
  -H "Content-Type: application/json" \
  -d '{"size_kb": 512}'
curl -X POST http://localhost:8080/runtime/z3-mem \
  -H "Content-Type: application/json" \
  -d '{"size_mb": 64}'

# CPU model
curl http://localhost:8080/runtime/cpu-model
curl -X POST http://localhost:8080/runtime/cpu-model \
  -H "Content-Type: application/json" \
  -d '{"model": 68030}'

# Window size
curl http://localhost:8080/runtime/window-size
curl -X POST http://localhost:8080/runtime/window-size \
  -H "Content-Type: application/json" \
  -d '{"width": 800, "height": 600}'

# Scaling mode (-1=auto, 0=nearest, 1=linear, 2=integer)
curl http://localhost:8080/runtime/scaling
curl -X POST http://localhost:8080/runtime/scaling \
  -H "Content-Type: application/json" \
  -d '{"mode": 1}'

# Line mode (single, double, scanlines)
curl http://localhost:8080/runtime/line-mode
curl -X POST http://localhost:8080/runtime/line-mode \
  -H "Content-Type: application/json" \
  -d '{"mode": "scanlines"}'

# Resolution (lores, hires, superhires)
curl http://localhost:8080/runtime/resolution
curl -X POST http://localhost:8080/runtime/resolution \
  -H "Content-Type: application/json" \
  -d '{"mode": "hires"}'

# Autocrop
curl http://localhost:8080/runtime/autocrop
curl -X POST http://localhost:8080/runtime/autocrop \
  -H "Content-Type: application/json" \
  -d '{"enabled": true}'

# WHDLoad
curl http://localhost:8080/runtime/whdload
curl -X POST http://localhost:8080/runtime/whdload \
  -H "Content-Type: application/json" \
  -d '{"path": "/path/to/game.lha"}'
curl -X DELETE http://localhost:8080/runtime/whdload

# Debugging and Diagnostics
curl -X POST http://localhost:8080/runtime/debug/activate
curl http://localhost:8080/runtime/debug/status
curl -X POST http://localhost:8080/runtime/debug/step \
  -H "Content-Type: application/json" \
  -d '{"count": 10}'
curl -X POST http://localhost:8080/runtime/debug/continue
curl -X POST http://localhost:8080/runtime/debug/deactivate
curl http://localhost:8080/runtime/cpu/regs
curl http://localhost:8080/runtime/custom/regs
curl -X POST http://localhost:8080/runtime/disassemble \
  -H "Content-Type: application/json" \
  -d '{"address": "0xFC0000", "count": 10}'
curl http://localhost:8080/runtime/breakpoints
curl -X POST http://localhost:8080/runtime/breakpoints \
  -H "Content-Type: application/json" \
  -d '{"address": "0x400"}'
curl -X DELETE http://localhost:8080/runtime/breakpoints \
  -H "Content-Type: application/json" \
  -d '{"address": "ALL"}'
curl http://localhost:8080/runtime/copper/state
curl http://localhost:8080/runtime/blitter/state
curl "http://localhost:8080/runtime/drive/state?drive=0"
curl http://localhost:8080/runtime/audio/state
curl http://localhost:8080/runtime/dma/state

# Keyboard input
curl -X POST http://localhost:8080/runtime/key \
  -H "Content-Type: application/json" \
  -d '{"keycode": 64, "state": 1}'   # Press SPACE (keycode 64)
curl -X POST http://localhost:8080/runtime/key \
  -H "Content-Type: application/json" \
  -d '{"keycode": 64, "state": 0}'   # Release SPACE

# Type text into emulation
curl -X POST http://localhost:8080/runtime/type \
  -H "Content-Type: application/json" \
  -d '{"text": "dir\n", "delay_ms": 50}'

# Utility
curl http://localhost:8080/runtime/version
curl http://localhost:8080/runtime/ping

API Endpoints

Core Endpoints

Endpoint	Method	Description
`/`	GET	API name, version, platform, status
`/status`	GET	Check if Amiberry is running
`/stop`	POST	Stop all Amiberry instances
`/configs`	GET	List configurations
`/disk-images`	GET	List disk images
`/savestates`	GET	List savestates
`/launch`	POST	Launch with full options
`/quick-launch/{name}`	POST	Quick launch by model/config
`/platform`	GET	Get platform info

Configuration Endpoints

Endpoint	Method	Description
`/configs/{name}`	GET	Get raw config file contents
`/configs/{name}/parsed`	GET	Get parsed config as JSON
`/configs/create/{name}`	POST	Create new config from template
`/configs/{name}`	PATCH	Modify existing config

Launch Endpoints

Endpoint	Method	Description
`/launch-with-logging`	POST	Launch with log capture
`/launch-lha`	POST	Launch an .lha archive directly
`/launch-whdload`	POST	Launch WHDLoad game
`/launch-cd`	POST	Launch CD image
`/launch-and-wait`	POST	Launch and wait until the IPC socket is ready
`/disk-swapper`	POST	Configure disk swapper

Media Endpoints

Endpoint	Method	Description
`/cd-images`	GET	List CD images
`/logs`	GET	List captured logs
`/logs/{name}`	GET	Get log content
`/logs/tail`	POST	Get new log lines since last read (incremental)
`/logs/wait-for-pattern`	POST	Wait for a regex pattern in log output

Analysis Endpoints

Endpoint	Method	Description
`/savestates/{name}/inspect`	GET	Get savestate metadata
`/roms`	GET	List identified ROMs
`/roms/identify`	GET	Identify a ROM by `rom_path` query parameter
`/version`	GET	Get Amiberry version

Process Lifecycle Endpoints

Endpoint	Method	Description
`/health`	GET	Combined check: process + IPC + emulation status
`/process/alive`	GET	Check if the Amiberry process is running
`/process/info`	GET	Detailed process info with crash detection
`/process/kill`	POST	Force kill a running/hung process
`/process/wait-for-exit`	POST	Wait for the process to exit
`/process/restart`	POST	Kill and re-launch with the same command
`/process/crash-info`	POST	Detect crashes via process state and log scanning

Runtime Control Endpoints

Emulation Control

Endpoint	Method	Description
`/runtime/status`	GET	Get emulation status
`/runtime/pause`	POST	Pause emulation
`/runtime/resume`	POST	Resume emulation
`/runtime/reset`	POST	Soft or hard reset
`/runtime/quit`	POST	Quit Amiberry
`/runtime/frame-advance`	POST	Advance N frames when paused

Media Control

Endpoint	Method	Description
`/runtime/insert-floppy`	POST	Insert floppy disk
`/runtime/eject-floppy`	POST	Eject floppy from drive
`/runtime/list-floppies`	GET	List all floppy drives
`/runtime/insert-cd`	POST	Insert CD image
`/runtime/eject-cd`	POST	Eject CD

State Management

Endpoint	Method	Description
`/runtime/screenshot`	POST	Take a screenshot
`/runtime/screenshot-view`	POST	Return exact screenshot bytes and actionable metadata
`/runtime/save-state`	POST	Save state while running
`/runtime/load-state`	POST	Load a savestate
`/runtime/quicksave`	POST	Quick save to slot (0-9)
`/runtime/quickload`	POST	Quick load from slot (0-9)

Audio Control

Endpoint	Method	Description
`/runtime/volume`	GET	Get current volume
`/runtime/volume`	POST	Set volume (0-100)
`/runtime/mute`	POST	Mute audio
`/runtime/unmute`	POST	Unmute audio

Display Control

Endpoint	Method	Description
`/runtime/fullscreen`	POST	Toggle fullscreen
`/runtime/warp`	GET	Get warp mode status
`/runtime/warp`	POST	Set warp mode
`/runtime/display-mode`	GET	Get display mode
`/runtime/display-mode`	POST	Set mode (0=window, 1=fullscreen, 2=fullwindow)
`/runtime/ntsc`	GET	Get video mode (PAL/NTSC)
`/runtime/ntsc`	POST	Set video mode (0=PAL, 1=NTSC)

Sound Control

Endpoint	Method	Description
`/runtime/sound-mode`	GET	Get sound mode
`/runtime/sound-mode`	POST	Set mode (0=off, 1=normal, 2=stereo, 3=best)

Joystick/Input Control

Endpoint	Method	Description
`/runtime/joyport/{port}`	GET	Get port mode
`/runtime/joyport`	POST	Set port mode
`/runtime/autofire/{port}`	GET	Get autofire mode
`/runtime/autofire`	POST	Set autofire mode

Floppy Control

Endpoint	Method	Description
`/runtime/floppy-speed`	GET	Get current floppy speed
`/runtime/floppy-speed`	POST	Set floppy speed (0=turbo, 100=1x, 200=2x, 400=4x, 800=8x)
`/runtime/disk-write-protect/{drive}`	GET	Get disk write protection status
`/runtime/disk-write-protect`	POST	Set disk write protection for drive

Display Control (additional)

Endpoint	Method	Description
`/runtime/rtg`	POST	Toggle between RTG and chipset display
`/runtime/status-line`	POST	Cycle status line (off/chipset/rtg/both)
`/runtime/fps`	GET	Get current frame rate and idle percentage

Input Control (additional)

Endpoint	Method	Description
`/runtime/mouse-grab`	POST	Toggle mouse capture/grab
`/runtime/mouse-speed`	GET	Get current mouse sensitivity

Hardware/Chipset Control

Endpoint	Method	Description
`/runtime/chipset`	GET	Get current chipset
`/runtime/chipset`	POST	Set chipset (OCS, ECS_AGNUS, ECS_DENISE, ECS, AGA)
`/runtime/cpu-speed`	GET	Get current CPU speed setting
`/runtime/cpu-speed`	POST	Set CPU speed (-1=max, 0=cycle-exact, >0=%)
`/runtime/memory-config`	GET	Get all memory sizes (chip, fast, bogo, z3, rtg)

Memory Configuration

Endpoint	Method	Description
`/runtime/chip-mem`	POST	Set Chip RAM size (256, 512, 1024, 2048, 4096, 8192 KB)
`/runtime/fast-mem`	POST	Set Fast RAM size (0, 1024, 2048, 4096, 8192 KB)
`/runtime/slow-mem`	POST	Set Slow/Bogo RAM size (0, 256, 512, 1024, 1792 KB)
`/runtime/z3-mem`	POST	Set Zorro III RAM size (0-1024 MB)
`/runtime/cpu-model`	GET	Get current CPU model
`/runtime/cpu-model`	POST	Set CPU model (68000, 68010, 68020, 68030, 68040, 68060)

Window/Display Control

Endpoint	Method	Description
`/runtime/window-size`	GET	Get current window dimensions
`/runtime/window-size`	POST	Set window size (width x height)
`/runtime/scaling`	GET	Get current scaling mode
`/runtime/scaling`	POST	Set scaling mode (-1=auto, 0=nearest, 1=linear, 2=integer)
`/runtime/line-mode`	GET	Get current line mode
`/runtime/line-mode`	POST	Set line mode (single, double, scanlines)
`/runtime/resolution`	GET	Get current resolution mode
`/runtime/resolution`	POST	Set resolution (lores, hires, superhires)
`/runtime/autocrop`	GET	Get current autocrop status
`/runtime/autocrop`	POST	Enable/disable automatic display cropping

WHDLoad Control

Endpoint	Method	Description
`/runtime/whdload`	GET	Get currently loaded WHDLoad game info
`/runtime/whdload`	POST	Load a WHDLoad game (LHA or directory)
`/runtime/whdload`	DELETE	Eject the currently loaded WHDLoad game

Debugging and Diagnostics

Endpoint	Method	Description
`/runtime/debug/activate`	POST	Activate the built-in debugger
`/runtime/debug/deactivate`	POST	Deactivate debugger and resume
`/runtime/debug/status`	GET	Get debugger status
`/runtime/debug/step`	POST	Single-step CPU instructions
`/runtime/debug/step-over`	POST	Step over subroutine calls (JSR/BSR)
`/runtime/debug/continue`	POST	Continue execution
`/runtime/cpu/regs`	GET	Get all CPU registers
`/runtime/custom/regs`	GET	Get custom chip registers
`/runtime/disassemble`	POST	Disassemble at address
`/runtime/breakpoints`	GET	List all breakpoints
`/runtime/breakpoints`	POST	Set a breakpoint
`/runtime/breakpoints`	DELETE	Clear breakpoint(s)
`/runtime/copper/state`	GET	Get Copper state
`/runtime/blitter/state`	GET	Get Blitter state
`/runtime/drive/state`	GET	Get floppy drive state
`/runtime/audio/state`	GET	Get audio channel states
`/runtime/dma/state`	GET	Get DMA channel states

Status

Endpoint	Method	Description
`/runtime/led-status`	GET	Get all LED states
`/runtime/harddrives`	GET	List mounted hard drives

Configuration

Endpoint	Method	Description
`/runtime/config/{option}`	GET	Get config option value
`/runtime/config`	POST	Set config option
`/runtime/configs`	GET	List available configs
`/runtime/load-config`	POST	Load a .uae config into the running emulation

Memory Access

Endpoint	Method	Description
`/runtime/memory/read`	POST	Read emulated Amiga memory (1/2/4 bytes)
`/runtime/memory/write`	POST	Write emulated Amiga memory (1/2/4 bytes)

Input Control

Endpoint	Method	Description
`/runtime/key`	POST	Send keyboard input (keycode + state)
`/runtime/type`	POST	Type a string of text character by character
`/runtime/mouse`	POST	Send mouse input
`/runtime/mouse-speed`	POST	Set mouse sensitivity

Screenshot-driven GUI Automation

Endpoint	Method	Description
`/runtime/gui/move`	POST	Move or hover using screenshot pixels
`/runtime/gui/click`	POST	Click or double-click using screenshot pixels
`/runtime/gui/drag`	POST	Drag using screenshot pixels

Utility

Endpoint	Method	Description
`/runtime/version`	GET	Get Amiberry version
`/runtime/ping`	GET	Test IPC connection
`/runtime/ipc-check`	GET	Check IPC availability
`/runtime/active-instance`	GET	Get the instance currently being controlled
`/runtime/active-instance`	POST	Set the instance to control (`null` to auto-discover)

Note: Runtime endpoints require Amiberry built with USE_IPC_SOCKET=ON

See docs/HTTP_API_GUIDE.md for complete documentation.

Auto-start

macOS:

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

Linux:

systemctl --user enable amiberry-http-api.service
systemctl --user start amiberry-http-api.service

Development

# Clone and setup
git clone https://github.com/BlitterStudio/amiberry-mcp-server.git
cd amiberry-mcp-server

# Create virtual environment
python3 -m venv venv
source venv/bin/activate

# Install with dev dependencies
pip install -e ".[all]"

# Run tests
pytest tests/ -v

# Lint and format
ruff check src/ tests/
ruff format src/ tests/

Troubleshooting

MCP tools not appearing in your client

Restart the MCP client completely (quit and reopen) — most clients only load MCP servers at startup
Check the command path in your client's config points at this project's venv/bin/python
Verify the virtual environment exists (ls venv/bin/python)
Run python -m amiberry_mcp.server directly — it should sit waiting for stdio input. If it errors, fix that first.
Inspect the client's MCP log:
- Claude Desktop (macOS): ~/Library/Logs/Claude/mcp*.log
- Claude Code: claude mcp list then check stderr for the server
- Cursor: View → Output → "MCP" channel

"Command not found" errors

Linux: Ensure amiberry is in your PATH
macOS: Verify Amiberry.app is in /Applications

Permission errors

Check that scripts are executable: chmod +x scripts/*.sh

View captured Amiberry logs

# macOS
ls ~/Documents/Amiberry/logs/

# Linux
ls ~/Amiberry/logs/

Runtime control not working

Ensure Amiberry was built with USE_IPC_SOCKET=ON (CMake option)
Check if the socket exists. It lives in $XDG_RUNTIME_DIR when that is set, otherwise /tmp: ls "${XDG_RUNTIME_DIR:-/tmp}/amiberry.sock"
With multiple instances, instance 0 uses amiberry.sock and the rest use amiberry_1.sock, amiberry_2.sock, … (searched up to instance 9) — pick one with set_active_instance
Verify Amiberry is running before using runtime control tools
Test the socket directly: echo "GET_STATUS" | nc -U "${XDG_RUNTIME_DIR:-/tmp}/amiberry.sock"

Uninstall

./scripts/uninstall.sh

Contributing

Contributions welcome! Please open an issue or pull request. See AGENTS.md for the architecture overview and code conventions (ruff config, type-annotation style, error handling, test layout).

License

GPL-3.0 License - see LICENSE file.

Resources

MCP Documentation
Amiberry Project
MCP-compatible clients: Claude Desktop, Claude Code, Codex, Cursor, Cline, Continue, Windsurf
FastAPI Documentation

from github.com/BlitterStudio/amiberry-mcp-server

Installing Amiberry

This server has no published package — it is built from source. Open the repository and follow its README.

▸ github.com/BlitterStudio/amiberry-mcp-server

FAQ

Is Amiberry MCP free?

Yes, Amiberry MCP is free — one-click install via Unyly at no cost.

Does Amiberry need an API key?

No, Amiberry runs without API keys or environment variables.

Is Amiberry hosted or self-hosted?

Self-hosted: the server runs locally on your machine via the install command above.

How do I install Amiberry in Claude Desktop, Claude Code or Cursor?

Open Amiberry on unyly.org, pick your client tab (Claude Desktop, Claude Code, Cursor) and press Install — the config is generated automatically, no JSON editing.

Related MCPs

GitHub

PRs, issues, code search, CI status

by GitHub

Filesystem

Secure file operations with configurable access controls.

by Community

Memory

Knowledge graph-based persistent memory system.

by Community

Template MCP Server

A CLI tool to create a new Model Context Protocol server project with TypeScript support, dual transport options, and an extensible structure

by mcpdotdirect

Compare Amiberry with

AmiberryvsGitHub AmiberryvsFilesystem AmiberryvsMemory AmiberryvsTemplate MCP Server

Not sure what to pick?

Find your stack in 60 seconds

Author?

Embed badge for your README

Browse similar

All development MCPs

Command Palette

Amiberry

About

README

Features

Core Features

Runtime Control

Developer/Debug Features

Autonomous Troubleshooting

Game Launcher Features

Requirements

Project Structure

Installation

Quick Install (Recommended)

Manual Installation

Client Configuration

Claude Desktop

Other MCP clients

Verification

Default Directory Structure

macOS

Linux

Available MCP Tools

Core Tools

Configuration Tools

Launch Tools

Media Tools

Analysis Tools

Runtime Control Tools

Emulation Control

Media Control

State Management

Audio Control

Display Control

Sound Control

Joystick/Input Control

Floppy Control

Display Control (additional)

Input Control (additional)

Hardware/Chipset Control

Memory Configuration

Window/Display Control

WHDLoad Control

Instance Control

Debugging and Diagnostics

Status

Configuration

Input Control

Utility

Process Lifecycle Management

Memory Access

Runtime Configuration

Screenshot Analysis

Log Tailing & Crash Detection

Workflow Automation

Screenshot-driven GUI automation

Usage Examples

Basic Usage

WHDLoad Games

CD32/CDTV Games

Configuration Management

Debugging

Savestate Analysis

Runtime Control

Keyboard Input

Debugging and Diagnostics

HTTP API

Quick Start

Example Commands

API Endpoints

Core Endpoints

Configuration Endpoints

Launch Endpoints

Media Endpoints

Analysis Endpoints

Process Lifecycle Endpoints

Runtime Control Endpoints

Auto-start

Development

Troubleshooting