MiSTerClaw

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

MiSTerClaw 是首个适用于 MiSTer-FPGA 的 MCP 服务。通过任意 AI Agent 控制你的 MiSTer。

（徽章建议：感谢 punkpeye。）

v0.8.1 新增了经过验证的原生 ZIP 成员启动功能，以及独立的 GBA2P 配置文件。有关下载和校验和，请参阅发布说明和硬件测试限制、ZIP 成员用法和 GitHub Releases。

这是什么？

MiSTerClaw 让 AI Agent（Claude、ChatGPT、OpenClaw、Hermes、Cursor 等）能够通过网络控制 MiSTer-FPGA。启动游戏、搜索 ROM 库、截取屏幕截图、读取和修改核心设置及 DIP 开关、使用基于 conf_str 的位置计算导航 OSD 菜单（实验性功能，目前对所有核心都不可靠）、查询详细的系统信息、管理系统，甚至设置 Tailscale VPN，以便从任何地方安全地远程访问。软盘核心（PC8801、MSX 等）支持 PostLaunch 自动重置，从而无缝加载游戏。它采用 Model Context Protocol（MCP）标准，因此任何兼容 MCP 的客户端都能开箱即用。对于不支持 MCP 的 Agent，也提供了 CLI 客户端。

街机游戏

街机游戏根据 .mra 描述文件建立索引并直接启动（初步支持：感谢 stt）；它们 不会显示为 MAME ZIP 文件夹或单个全系统 RBF。SD 卡和 USB 上支持递归 规范文件夹及 _alternatives。当同一根目录中存在规范描述文件时，会省略生成的 _Organized 视图；仅包含整理后内容的集合仍可作为备用方案使用。相同字节内容的 备用描述文件会去重，而不同变体则会保留。数量表示已建立索引的描述文件／变体数， 而非唯一游戏系列数。缓存架构 v3 会原地升级旧版 v1/v2 街机和 MAME 条目，同时保留 无关的已缓存系统；升级时无需完整重新扫描 ROM。

针对特定位置的 SD 卡重新扫描也会刷新 _Arcade，并合并现有的 SD／USB 街机文件夹，而不是将其替换。位置重新扫描现在会立即返回 status: pending；请轮询 systems.scanning，直到其变为 false。 刷新期间仍可使用现有结果。对于重叠扫描或无效位置的请求会明确失败。MRA 启动会验证文件、 重新创建虚拟输入设备，并在 core_name 中报告描述文件指定的 <rbf>；此响应本身并不能证明 FPGA 已完成加载。

MCP 设置

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

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 工具

工具	描述
mister_status	当前正在播放的内容
mister_launch	按搜索结果或路径启动游戏
mister_search	搜索 ROM 库
mister_systems	列出所有可用系统及其 ROM 数量
mister_screenshot	截取屏幕（返回 PNG 图像）
mister_info	系统信息（主机名、IP、温度、RAM、磁盘、运行时间）
mister_input	发送键盘输入（OSD 导航、命名按键）
mister_osd_info	从 CONF_STR 数据库查询 OSD 菜单结构
mister_osd_visible	根据当前配置仅显示可见的 OSD 菜单项
mister_cfg_read	读取核心设置（选项 + DIP 开关）
mister_cfg_write	修改核心设置并自动备份
mister_reload	重新加载当前核心以应用配置更改
mister_osd_navigate	按名称导航到特定 OSD 菜单项
mister_system_info	获取系统配置、说明和 OSD 菜单
mister_rescan	重新扫描 ROM 库（可指定驱动器）
mister_tailscale	管理 Tailscale VPN
mister_shell	执行 shell 命令（初始输出处理修复：感谢 stt）

对话示例

配置完成后，直接与 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.

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 的 Agent（如 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，可输出机器可读的结果。

安装

共有三个二进制文件：

二进制文件	运行位置	用途
misterclaw	MiSTer（ARM7）	服务端——在 MiSTer 本机运行
misterclaw-send	任意位置	用于直接执行命令的 CLI 客户端
misterclaw-mcp	你的机器	MCP 服务——将 AI Agent 连接到 MiSTer

下载和支持的平台

请从 GitHub Releases 下载可执行文件，而非从源代码仓库下载。发布工作流会构建以下目标：

平台	架构	下载内容
MiSTer	Linux ARMv7	misterclaw-linux-arm7 守护进程
Linux	x86-64、ARM64、ARMv7	CLI 和 MCP 服务
macOS	Intel x86-64、Apple Silicon ARM64	CLI 和 MCP 服务
Windows	x86-64	CLI 和 MCP 服务（.exe）

Windows 下载从 v0.8.0 开始提供；较早版本可能不包含这些文件。守护进程只能在 MiSTer 上运行，不能在 Windows 或 macOS 上运行。在 Linux/macOS 上，使用 chmod +x <filename> 将下载的客户端设为可执行文件。

在 Windows 上，可在 PowerShell 中使用下载的可执行文件，例如：

.\misterclaw-send-windows-amd64.exe -H mister-fpga status

将 MCP 客户端的 command 指向 misterclaw-mcp-windows-amd64.exe 的绝对路径；JSON 路径中的反斜杠必须转义，例如 C:\\Tools\\misterclaw-mcp-windows-amd64.exe。

发布工作流会构建带标签的版本（初始工作流：感谢 stt）。新的 CI 生成版本包含 SHA256SUMS 和 build-metadata.json，记录源代码提交、编译器版本和目标清单。分支/PR/手动 CI 运行只会生成预览构件。发布要求从 main 历史推送版本标签并通过测试；维护者必须在推送标签前确认发布和许可准备就绪。提交历史包含 main 本身并不能证明已获审查批准。添加 CI 不会创建新版本。

在 MiSTer 上快速安装

scp misterclaw root@<mister-ip>:/media/fat/Scripts/
ssh root@<mister-ip> "/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 服务和命令行客户端通过 ClawExec 协议与 MiSTer 通信（通过 TCP 传输以换行符分隔的 JSON，端口为 9900）。

动态系统检测

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/

许可证

MIT