👾🦀 MiSTerClaw — MCP Remote Control for MiSTer-FPGA

MiSTerClaw might be the first MCP server for MiSTer-FPGA. Control your MiSTer from any AI agent.

-blue)

What is this?

MiSTerClaw lets AI agents — Claude, ChatGPT, OpenClaw, Hermes, Cursor, and others — control a MiSTer-FPGA over the network. Launch games, search your ROM library, take screenshots, manage the system, and even set up Tailscale VPN for secure remote access from anywhere. It uses the Model Context Protocol (MCP) standard, so any MCP-compatible client works out of the box. For agents without MCP support, a CLI client is also included.

MCP Setup

Add MiSTerClaw to your MCP client config:

Claude Desktop (claude_desktop_config.json):

{

  "mcpServers": {

    "misterclaw": {

      "command": "/path/to/misterclaw-mcp",

      "args": ["--host", "mister-fpga"]

    }

  }

}

Cursor (.cursor/mcp.json):

{

  "mcpServers": {

    "misterclaw": {

      "command": "/path/to/misterclaw-mcp",

      "args": ["--host", "mister-fpga"]

    }

  }

}

MCP Tools

| Tool | Description |
|------|-------------|
| 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_tailscale | Manage Tailscale VPN |
| mister_shell | Execute shell commands |

Example Conversations

Once configured, just talk to your agent:

You: "What games do I have for SNES?"
Agent: You have 13,435 SNES ROMs! Here are some highlights...
You: "Launch Street Fighter 2"

Agent: 🎮 Launched Street Fighter II Turbo on SNES!
You: "Take a screenshot and show me"

Agent: [screenshot of the game running]
You: "What systems do I have?"

Agent: Your MiSTer has 70+ systems! Top ones:

  - SNES: 13,435 ROMs

  - C64: 46,736 ROMs

  - Amiga: 55,793 ROMs

  ...
You: "Set up Tailscale so I can reach the MiSTer from anywhere"

Agent: Installing Tailscale... Done!

       Please authenticate: https://login.tailscale.com/a/xxx

       After that your MiSTer is reachable from anywhere.

CLI Client

For systems that don't support MCP, MiSTerClaw also includes a CLI client.

misterclaw-send -H mister-fpga search "sonic"
misterclaw-send -H mister-fpga launch "sonic 2" --system MegaDrive
misterclaw-send -H mister-fpga systems
misterclaw-send -H mister-fpga screenshot -o game.png

Installation

Three binaries:

| Binary | Runs on | Purpose |
|--------|---------|---------|
| misterclaw | MiSTer (ARM7) | Server — runs on the MiSTer itself |
| misterclaw-send | Anywhere | CLI client for direct commands |
| misterclaw-mcp | Your machine | MCP server — bridges AI agents to MiSTer |

Quick install on MiSTer

scp misterclaw root@<mister-ip>:/media/fat/Scripts/
ssh root@<mister-ip> "/media/fat/Scripts/misterclaw --install"

Or self-install: copy the binary to MiSTer, then run misterclaw --install. This copies to /media/fat/Scripts/, configures autostart on boot, and is idempotent.

To uninstall: /media/fat/Scripts/misterclaw --uninstall

Security

> ⚠️ Do not expose port 9900 to the internet. The ClawExec protocol has no authentication or encryption.

- Tailscale VPN (recommended) — encrypted, authenticated, works from anywhere
- Local network only — keep port 9900 accessible within your LAN
- Never forward port 9900 through your router or firewall

Architecture

Agent ←MCP→ misterclaw-mcp ←TCP→ MiSTer:9900 (misterclaw server)
Agent ←CLI→ misterclaw-send ←TCP→ MiSTer:9900 (misterclaw server)

The MCP server and CLI client communicate with the MiSTer over the ClawExec protocol (newline-delimited JSON over TCP, port 9900).

Dynamic System Detection

MiSTerClaw auto-detects all systems by scanning ROM folders, installed cores, and MGL files. No configuration needed — a well-stocked MiSTer typically has 70+ systems. Discovery runs in the background at server startup and results are cached in memory.

Building from Source

```bash