Mi S Ter Claw

👾🦀 MiSTerClaw——用于MiSTer FPGA的MCP远程控制

MiSTerClaw是第一个用于MiSTer FPGA的MCP服务器。从任何AI代理控制你的MiSTer。

![Platform]()

这是什么？

MiSTerClaw允许人工智能代理（Claude、ChatGPT、OpenClaw、Hermes、Cursor等）通过网络控制MiSTer FPGA。启动游戏、搜索ROM库、截图、读取和修改核心设置和DIP开关、使用基于conf_str的位置计算（实验性，尚未对所有核心可靠）导航OSD菜单、查询详细的系统信息、管理系统，甚至设置Tailscale VPN以从任何地方进行安全的远程访问。软盘核心（PC8801、MSX等）支持启动后自动重置，以实现无缝游戏加载。它使用 模型上下文协议（MCP） 标准，因此任何兼容MCP的客户端都可以开箱即用。对于不支持MCP的代理，还包括CLI客户端。

MCP设置

将MiSTerClaw添加到MCP客户端配置中：

克劳德桌面版 (claude_desktop_config.json):

{
  "mcpServers": {
    "misterclaw": {
      "command": "/path/to/misterclaw-mcp",
      "args": ["--host", "mister-fpga"]
    }
  }
}

光标 (.cursor/mcp.json):

{
  "mcpServers": {
    "misterclaw": {
      "command": "/path/to/misterclaw-mcp",
      "args": ["--host", "mister-fpga"]
    }
  }
}

MCP工具

对话示例

配置后，只需与您的代理交谈：

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.

You: "What settings does R-Type have?"
Agent: R-Type (M72 core) has these settings:
       Core Options:
         - No Death Mode: Off
         - Service Mode: Off
       DIP Switches:
         - Difficulty: Medium
         - Coin A: 1 Coin / 1 Credit
         - Lives: 3
         - Demo Sounds: On
         - Continue: Yes

You: "Enable No Death Mode"
Agent: ⚙️ Set "No Death Mode" to On in R-Type.
       The core reloads automatically — change is live!

You: "Navigate to the Reset option in the OSD"
Agent: Navigated to Reset in the SNES core OSD.

You: "What do I need to know about the PC8801 system?"
Agent: PC8801 uses the PC8801 core with .d88 floppy disk images.
       Notes: After loading a disk, press F12 → Reset to boot.
       OSD Menu: FDD0, FDD1, Reset, CPU Speed, ...

CLI客户端

对于具有shell访问权限的代理（如OpenClaw、Codex或Claude Code），CLI客户端可以比MCP更高效——上下文中没有工具模式，只需在需要时调用它。它对shell脚本和自动化也很有用。

# Check what's playing
misterclaw-send -H mister-fpga status

# Search for games
misterclaw-send -H mister-fpga search "zelda" --limit 5
misterclaw-send -H mister-fpga search "sonic" --system MegaDrive

# Launch a game
misterclaw-send -H mister-fpga launch "super mario world" --system SNES

# List all systems with ROM counts
misterclaw-send -H mister-fpga systems

# Take a screenshot
misterclaw-send -H mister-fpga screenshot -o game.png

# System info (CPU, memory, storage, uptime)
misterclaw-send -H mister-fpga info

# Run shell commands — configure MiSTer.ini, run updates, manage files
misterclaw-send -H mister-fpga shell "cat /media/fat/MiSTer.ini"
misterclaw-send -H mister-fpga shell "/media/fat/Scripts/update_all.sh"

# Send keyboard input (OSD navigation)
misterclaw-send -H mister-fpga input key osd
misterclaw-send -H mister-fpga input combo leftalt f12

# Query OSD menu structure
misterclaw-send -H mister-fpga osd-info
misterclaw-send -H mister-fpga osd-info --core SNES

# Navigate to a specific OSD menu item
misterclaw-send -H mister-fpga osd-navigate Reset
misterclaw-send -H mister-fpga osd-navigate "Aspect ratio"

# Get detailed system info (config, notes, OSD menu)
misterclaw-send -H mister-fpga system-info PC8801
misterclaw-send -H mister-fpga system-info SNES

# Read core settings (options + DIP switches)
misterclaw-send -H mister-fpga cfg-read

# Modify settings
misterclaw-send -H mister-fpga cfg-write --option "Free Play" --value On

# Reload core to apply changes
misterclaw-send -H mister-fpga reload

# Rescan ROM library (after adding new games)
misterclaw-send -H mister-fpga rescan
misterclaw-send -H mister-fpga rescan --location usb0

# JSON output for scripting
misterclaw-send -H mister-fpga status --json
misterclaw-send -H mister-fpga systems --json

所有命令支持 --json 用于机器可读输出。

安装

三个二进制文件：

在MiSTer上快速安装

scp misterclaw root@:/media/fat/Scripts/
ssh root@ "/media/fat/Scripts/misterclaw --install"

或者自行安装：将二进制文件复制到MiSTer，然后运行 misterclaw --install。此副本复制到 /media/fat/Scripts/，在启动时配置自动启动，并且是幂等的。

要卸载，请执行以下操作： /media/fat/Scripts/misterclaw --uninstall

安全

⚠️ 请勿将端口9900暴露于互联网。 ClawExec协议没有身份验证或加密。

• Tailscale VPN （推荐）--加密、经过身份验证，可在任何地方工作
• 仅限本地网络 --在局域网内保持端口9900可访问
• 从不 通过路由器或防火墙转发端口9900

建筑

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

MCP服务器和CLI客户端通过ClawExec协议（TCP上换行的JSON，端口9900）与MiSTer通信。

动态系统检测

MiSTerClaw通过扫描ROM文件夹、已安装的内核和MGL文件自动检测所有系统。无需配置——库存充足的MiSTer通常有70多个系统。发现结果（包括完整的ROM文件列表）被缓存到磁盘。第一次启动扫描并构建缓存；随后立即开始加载。使用 rescan 添加新游戏或驱动器后的命令。

从源头构建

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

许可证

麻省理工学院