# catallo/misterclaw [Health: Active]

**Category:** 📟 Embedded System  
**Repository:** https://github.com/catallo/misterclaw  
**GitHub Stars:** 6  
**Views:** 4  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/catallo-misterclaw

## Description
MiSTerClaw — MCP remote control for MiSTer-FPGA. Launch games, search ROMs, take screenshots, manage systems, and set up Tailscale VPN. Auto-discovers 70+ systems with dynamic core/ROM scanning.

## Tools
Capabilities this server exposes over MCP:

- **mister_status** — What's currently playing
- **mister_launch** — Launch a game by search or path
- **mister_search** — Search the ROM library
- **mister_systems** — List all available systems with ROM counts
- **mister_screenshot** — Take a screenshot (returns PNG image)
- **mister_info** — System info (hostname, IP, temp, RAM, disks, uptime)
- **mister_input** — Send keyboard input (OSD navigation, named keys)
- **mister_osd_info** — Query OSD menu structure from CONF_STR database
- **mister_osd_visible** — Show only visible OSD menu items based on current config
- **mister_cfg_read** — Read core settings (options + DIP switches)
- **mister_cfg_write** — Modify core settings with automatic backup
- **mister_reload** — Reload current core to apply config changes
- **mister_osd_navigate** — Navigate to a specific OSD menu item by name
- **mister_system_info** — Get system config, notes, and OSD menu for a system
- **mister_rescan** — Rescan ROM library (optionally for specific drive)
- **mister_tailscale** — Manage Tailscale VPN
- **mister_shell** — Execute shell commands

## Claude Desktop Quick Installation
Heuristic fallback — verify the package name and runner against the repository README before running it. Uses `npx` (confidence: low):

```json
"mcpServers": {
  "misterclaw": {
    "command": "npx",
    "args": ["-y","catallo-misterclaw"]
  }
}
```

## Documentation

## 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.

_Full upstream README: https://allmcps.com/mcp/catallo-misterclaw/readme_