Misterclaw

What catallo/misterclaw MCP server does

catallo/misterclaw MCP server gives an AI agent remote control of a MiSTer-FPGA system. It can report the active game, search the ROM library, launch a title by search or path, list detected systems and ROM counts, and return screenshots as PNG images. It also exposes host information such as the hostname, IP address, temperature, memory, disks, and uptime.

The server covers MiSTer administration as well as game control. Agents can send named keyboard input, inspect and navigate the on-screen display, read core options and DIP switches, update those settings with automatic backups, reload a core, and rescan ROM storage. Additional tools manage Tailscale and execute shell commands on the MiSTer, so shell access should be treated as a significant operational capability.

How it works

The project has three binaries with separate roles: misterclaw runs on the MiSTer, misterclaw-mcp provides the MCP interface on the agent's machine, and misterclaw-send offers direct command-line access. The MCP bridge and CLI communicate with the MiSTer server using the ClawExec protocol, which is newline-delimited JSON over TCP on port 9900.

System discovery scans ROM folders, installed cores, and MGL files. Results, including ROM listings, are cached on disk after the initial scan. Run a rescan after adding games or connecting another drive. OSD inspection uses core CONF_STR data; position-based navigation is described as experimental and may not work reliably with every core.

Setup and configuration

Install the MiSTer binary by copying it to the device and running misterclaw --install. The installer places it under /media/fat/Scripts/, configures startup at boot, and can be run repeatedly. Uninstallation uses the corresponding --uninstall option. The MCP bridge must then be configured with the MiSTer hostname or address through its --host argument.

The README documents configurations for Claude Desktop and Cursor. A typical setup has the MCP client launch misterclaw-mcp and pass --host with the MiSTer host name. From a source checkout, the three binaries can be built with Go; the MiSTer target uses Linux ARMv7, while the CLI and MCP bridge use the local build target.

Do not expose port 9900 directly to the internet. The ClawExec connection has no authentication or encryption. Use a local network or Tailscale, which the tool can help configure, for remote access.

Tools and capabilities

The exposed MCP tools support:

• Game status, ROM search, game launching, system listings, and library rescans.
• Screenshots and hardware or operating-system information.
• Keyboard input, OSD structure queries, visible-menu filtering, and named-item navigation.
• Reading and writing core options and DIP switches, followed by core reloads.
• Per-system configuration, notes, and OSD information.
• Tailscale management and arbitrary shell command execution.

catallo/misterclaw MCP server also includes a CLI client for scripts and agents that can invoke shell commands directly. CLI commands support JSON output for automation.

Limitations and notes

The MiSTer-side service must be reachable from the MCP bridge over TCP. The material does not describe built-in authentication, TLS, access control, or a hosted endpoint. Network placement is therefore part of the security model.

OSD navigation based on CONF_STR is experimental. Core settings may cause a reload when changed, and configuration writes create an automatic backup. Dynamic discovery depends on the ROM folders, installed cores, and MGL files available on the MiSTer at scan time.

catallo/misterclaw MCP server is released under the MIT license and targets MiSTer hardware, including the ARMv7 DE10-Nano platform.