Skip to content

MCP Server

Jump to bottom
Dimitris Panokostas edited this page Oct 17, 2026 · 6 revisions

Amiberry MCP Server

The Amiberry MCP Server is a Model Context Protocol (MCP) server that enables AI assistants (such as Claude Desktop, Claude Code, Codex, Gemini/Antigravity, Cursor, Cline, and Windsurf) to inspect and control the Amiberry emulator.

It communicates with MCP clients over standard input/output (stdio) and connects to running Amiberry instances over IPC: a Unix-domain socket on Linux, macOS and FreeBSD, and a named pipe on Windows. It also provides an optional standalone HTTP API built with FastAPI for automation scripts, webhooks, and voice assistants (Siri, Google Assistant).

Platform Support

The MCP server runs on:

  • Linux
  • macOS
  • FreeBSD
  • Windows

The MCP server raises RuntimeError on other operating systems. Runtime control requires an Amiberry build with USE_IPC_SOCKET=ON, the default on Linux, macOS, FreeBSD and Windows. On Windows that means Amiberry builds after 8.4.1 (BlitterStudio/amiberry#2466), which listen on the named pipe \\.\pipe\amiberry (further instances \\.\pipe\amiberry_1 to \\.\pipe\amiberry_9). The server finds those pipes by listing \\.\pipe\ and needs asyncio's Proactor event loop, which is the Windows default.

Installation and Setup

Prerequisites

  • Python 3.10 or higher

  • Amiberry installed:

    • macOS: /Applications/Amiberry.app
    • Linux and FreeBSD: amiberry binary available in PATH
    • Windows: Amiberry.exe from the installer (found through its registry entry and default install folder) or on PATH

    Set AMIBERRY_BINARY to the full path of the executable to use a portable install or a development build on any platform.

Quick Install

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

The installer will:

  1. Create a Python virtual environment (venv).
  2. Install required Python packages.
  3. Automatically configure detected MCP clients: Claude Desktop, Claude Code, Codex, and Gemini (Antigravity).

Manual Client Configuration

For any MCP-compatible client that supports stdio transports, configure the server with:

  • Command: /path/to/amiberry-mcp-server/venv/bin/python
  • Args: ["-m", "amiberry_mcp.server"]

Claude Desktop

Edit your configuration file:

  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
  • Linux: ~/.config/Claude/claude_desktop_config.json 
{
  "mcpServers": {
    "amiberry": {
      "command": "/path/to/amiberry-mcp-server/venv/bin/python",
      "args": ["-m", "amiberry_mcp.server"]
    }
  }
}

Claude Code

In ~/.claude.json:

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

Codex

In ~/.codex/config.toml:

[mcp_servers.amiberry]
command = "/path/to/amiberry-mcp-server/venv/bin/python"
args = ["-m", "amiberry_mcp.server"]

Cursor

In ~/.cursor/mcp.json (or .cursor/mcp.json in your project root):

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

Available Tool Groups

The server provides 150 tools. Tools whose names begin with runtime_ interact with running Amiberry instances over IPC; other tools operate on files, configurations, and processes.

Core and File Management

  • list_configs: List available .uae configuration files.
  • get_config_content: Read the contents of a configuration file.
  • list_disk_images: Search for floppy, hardfile, and LHA disk images (ADF, ADZ, DMS, HDF, HDZ, LHA); CD images (ISO, CUE, CHD, BIN, NRG) are found by list_cd_images.
  • launch_amiberry: Launch Amiberry with a configuration, Quickstart model preset, floppy disk, or WHDLoad archive.
  • list_savestates: List available .uss savestate files.
  • get_platform_info: Display platform detection, binary locations, and content paths.

Configuration Management

  • parse_config: Parse a .uae configuration file into structured key-value data.
  • modify_config: Update or insert specific configuration options in a .uae file.
  • create_config: Generate a new configuration from a built-in model template (A500, A500P, A600, A1200, A4000, CD32, CDTV).

Media and Launching

  • launch_with_logging: Launch Amiberry with console logging enabled and capture output to a file.
  • launch_whdload: Search for and launch WHDLoad games from .lha archives.
  • launch_cd: Launch CD images (ISO, CUE, CHD) with automatic system selection.
  • set_disk_swapper: Preload disk images into the Disk Swapper list.
  • list_cd_images: List available CD image files.
  • list_logs: List captured session log files.
  • get_log_content: Read captured log output.

Savestates and ROMs

  • inspect_savestate: Parse binary metadata from .uss savestates, including emulator version, CPU/FPU models, and actual RAM bank sizes.
  • list_roms: Catalog available Kickstart ROM files and identify them by CRC32 checksum.
  • identify_rom: Look up ROM metadata and official names by checksum.
  • get_amiberry_version: Query the installed Amiberry version.

Runtime Control (via IPC)

These tools interact with a running emulator over the IPC socket or, on Windows, the named pipe:

  • Emulation Control: pause_emulation, resume_emulation, reset_emulation (soft/hard), runtime_frame_advance.
  • Media Control: runtime_insert_floppy, runtime_eject_floppy, runtime_list_floppies, runtime_disk_swap, runtime_query_disk_swap, runtime_insert_cd, runtime_eject_cd, runtime_set_floppy_speed, runtime_get_floppy_speed, runtime_disk_write_protect, runtime_get_disk_write_protect.
  • State Management: runtime_screenshot, runtime_save_state, runtime_load_state, runtime_quicksave, runtime_quickload.

    Note: runtime_save_state and runtime_quicksave are refused while the debugger has the CPU stopped; pause emulation or resume execution first.

  • Configuration & Status: get_runtime_status, runtime_get_config, runtime_set_config, runtime_list_configs, runtime_load_config, runtime_get_led_status, runtime_list_harddrives.
  • Audio and Display: runtime_set_volume, runtime_get_volume, runtime_mute, runtime_unmute, runtime_toggle_fullscreen, runtime_set_warp, runtime_get_warp, runtime_set_display_mode, runtime_get_display_mode, runtime_set_ntsc, runtime_get_ntsc, runtime_set_sound_mode, runtime_get_sound_mode, runtime_toggle_rtg, runtime_toggle_status_line, runtime_get_fps.
  • Hardware and Memory: runtime_set_chipset, runtime_get_chipset, runtime_set_cpu_speed, runtime_get_cpu_speed, runtime_get_cpu_model, runtime_set_cpu_model, runtime_get_memory_config, runtime_set_chip_mem, runtime_set_fast_mem, runtime_set_slow_mem, runtime_set_z3_mem.
  • Window and Video: runtime_set_window_size, runtime_get_window_size, runtime_set_scaling (-1 auto, 0 nearest, 1 linear, 2 integer, 3 stretch), runtime_get_scaling, runtime_set_line_mode, runtime_get_line_mode, runtime_set_resolution, runtime_get_resolution, runtime_set_autocrop, runtime_get_autocrop.
  • Input and Joysticks: runtime_get_joyport_mode, runtime_set_joyport_mode, runtime_get_autofire, runtime_set_autofire, runtime_toggle_mouse_grab, runtime_get_mouse_speed, runtime_set_mouse_speed, runtime_send_key (by key name or scancode), runtime_send_text (types strings, handling shift for uppercase and symbols), runtime_send_mouse (relative deltas and buttons).
  • WHDLoad: runtime_insert_whdload, runtime_eject_whdload, runtime_get_whdload.
  • Multi-Instance Targeting: get_active_instance, set_active_instance (switch targeting between amiberry.sock, amiberry_1.sock, etc., or \\.\pipe\amiberry, \\.\pipe\amiberry_1, etc. on Windows).
  • Utility: runtime_get_version, runtime_ping, runtime_help, runtime_quit, check_ipc_connection.

Memory Access

  • runtime_read_memory: Read emulated memory (width: 1, 2, or 4 bytes).
  • runtime_write_memory: Write emulated memory (width: 1, 2, or 4 bytes).

Screenshot-Driven GUI Automation

Enables reliable automation of AmigaOS and application GUIs:

  1. runtime_screenshot_view: Captures an actionable screenshot, returning base64 image data and metadata (image dimensions and actionable pixel bounds).
  2. runtime_gui_move: Move or hover the mouse at an exact screenshot pixel coordinate.
  3. runtime_gui_click: Click or double-click a named button (left, right, middle) at a captured pixel coordinate.
  4. runtime_gui_drag: Drag a named button between two captured pixel coordinates.

Coordinates are provided in screenshot pixel space; the server translates coordinates across HiDPI displays, viewports, and scaling modes automatically.

Debugger and Diagnostics

  • runtime_debug_activate: Activate the built-in debugger.
  • runtime_debug_deactivate: Deactivate the debugger and resume emulation.
  • runtime_debug_status: Query debugger status. Reports active, stopped, debugging, exception_debugging, and reason (such as T05breakpoint:N;, T05watch:..., T05winuae-exception:..., or T05winuae-entry:...).
  • runtime_debug_step: Single-step CPU instructions.
  • runtime_debug_step_over: Step over subroutine calls (JSR/BSR).
  • runtime_debug_continue: Continue execution until the next breakpoint.
  • runtime_get_cpu_regs: Read integer CPU registers (D0-D7, A0-A7, PC, SR, USP, ISP).
  • runtime_get_custom_regs: Read custom chip registers (DMACON, INTENA, INTREQ, etc.).
  • runtime_disassemble: Disassemble instructions at a memory address.
  • runtime_set_breakpoint: Set a standard PC breakpoint. The optional slot argument (0-19) allows picking an explicit slot; slots holding monitor conditions are skipped and protected.
  • runtime_clear_breakpoint: Clear a specific breakpoint address or all standard PC breakpoints (ALL). Monitor conditions are preserved.
  • runtime_list_breakpoints: List active standard PC breakpoints.
  • runtime_get_copper_state: Query Copper coprocessor state.
  • runtime_get_blitter_state: Query Blitter activity and channel configurations.
  • runtime_get_drive_state: Query floppy drive track, motor, and disk presence.
  • runtime_get_audio_state: Query audio channel period, volume, and DMA status.
  • runtime_get_dma_state: Query DMA channel activity masks.

Debugger Monitor Tools

Amiberry exposes the GDB monitor commands over IPC through MONITOR <text> in builds after 8.4.1 (BlitterStudio/amiberry#2464). The MCP server provides typed tools that build commands, validate arguments, and parse JSON replies:

  • runtime_monitor: Send raw monitor command text.
  • runtime_execution_status: Query execution state, frame number, and beam position.
  • runtime_tasks: Query Exec current, ready, and waiting task lists.
  • runtime_segments: Query loaded AmigaDOS segments and code addresses.
  • runtime_memory: Query physical memory map (map) or verify writable RAM spans (check).
  • runtime_exception: Query exception capture status (status) or configure exception vector masks (mask).
  • runtime_watch: Manage CPU/DMA data watchpoint predicates (add, range, list, remove, events, last, clear-events).
  • runtime_dma_watch: Manage custom chip DMA watches (add, list, remove).
  • runtime_condition: Manage conditional register breakpoints (add, list, remove).
  • runtime_history: Control instruction history recording (on, off, read).
  • runtime_guest_output: Capture guest debug strings from uaelib function 86 (on, off, read, clear).
  • runtime_process_break: Arm one-shot stops at program entry (name, address, status, clear).
  • runtime_input: Inject keyboard, mouse, and joystick events directly (event, release, status).

Rules for Monitor Tools:

  • Read-only queries work while the emulator is running (with cpu_threaded=true, guest memory reads are refused).
  • State-changing commands (watch add/range/remove, condition add/remove, exception-mask, history on/off, process-break) require emulation to be paused (pause_emulation) or stopped in the native debugger.
  • When a monitor watch, condition, exception, or program-entry breakpoint hits without GDB attached, execution halts in the native debugger and runtime_debug_status reports the stop reason in reason.
  • GDB client commands (step-over, checkpoint, input sequence) are refused over IPC; use runtime_debug_step_over, runtime_save_state, and runtime_input event.

Process Lifecycle and Troubleshooting

  • check_process_alive: Check process status by PID.
  • get_process_info: Retrieve process details, uptime, and detect crash signals.
  • kill_amiberry: Terminate a running or hung Amiberry process.
  • wait_for_exit: Wait for an Amiberry process to exit within a timeout.
  • restart_amiberry: Kill and re-launch Amiberry with the same command-line arguments.
  • tail_log: Read newly appended lines from session logs incrementally.
  • wait_for_log_pattern: Block until a regex pattern appears in log output.
  • get_crash_info: Analyze process exit codes and logs to diagnose crashes.
  • health_check: Combined process, IPC, emulation status, and frame rate diagnostic.
  • launch_and_wait_for_ipc: Launch Amiberry and wait until the IPC socket is ready to accept commands.

HTTP API

The MCP server package includes an optional standalone HTTP server built with FastAPI. It exposes Amiberry controls as standard REST endpoints, ideal for command-line tools (curl), scripts, Siri Shortcuts, and home automation systems.

Starting the HTTP Server

# Start the HTTP server (default port 8080)
./scripts/start_http_api.sh

Interactive OpenAPI documentation is available in your browser at: http://localhost:8080/docs

Example HTTP Requests

# Quick-launch an Amiga model preset
curl -X POST http://localhost:8080/quick-launch/A1200

# Query emulation status
curl http://localhost:8080/status

# Pause and resume
curl -X POST http://localhost:8080/runtime/pause
curl -X POST http://localhost:8080/runtime/resume

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

# Capture an actionable screenshot for GUI automation
curl -X POST http://localhost:8080/runtime/screenshot-view \
  -H "Content-Type: application/json" \
  -d '{}'

# Send a GUI click at screenshot pixel coordinates
curl -X POST http://localhost:8080/runtime/gui/click \
  -H "Content-Type: application/json" \
  -d '{
    "capture_id": "<capture_id_from_screenshot_view>",
    "request_id": "req-001",
    "x": 320,
    "y": 200,
    "button": "left"
  }'

# Run a raw GDB monitor command
curl -X POST http://localhost:8080/runtime/debug/monitor \
  -H "Content-Type: application/json" \
  -d '{"text": "execution-status"}'

See Also

Getting Started

Loading Amiga Programs

Amiberry GUI

Input & Controllers

Advanced & Integration

Development

Clone this wiki locally