MiSTerClaw

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

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

# MiSTer server (ARM7)
GOOS=linux GOARCH=arm GOARM=7 go build -ldflags="-s -w" -o misterclaw ./cmd/misterclaw/

# CLI client
go build -ldflags="-s -w" -o misterclaw-send ./cmd/misterclaw-send/

# MCP server
go build -ldflags="-s -w" -o misterclaw-mcp ./cmd/misterclaw-mcp/

License

MIT