misterclaw MCP server
Commit Oct 11, 2026Lets AI agents control a MiSTer-FPGA over a network to launch games, search ROM libraries, and modify core settings.
Also known as catallo/misterclaw
- Stars
- 10
- Tools
- 17
- Downloads, 30 days
- —
- Latest version
- —
- Last commit
- Oct 11, 2026
- License
- MIT
What is misterclaw MCP?
misterclaw lets AI agents control a MiSTer-FPGA over a network to launch games, search ROM libraries, and modify core settings. It exposes 17 tools, such as mister_status, mister_launch, mister_search.
Summary generated from the project's README
About misterclaw MCP server
MiSTerClaw provides a bridge between AI agents and MiSTer-FPGA hardware over a network. It allows users to connect compatible clients like Claude Desktop, Cursor, or ChatGPT to their gaming hardware to manage a vast library of retro systems. The server enables agents to perform tasks such as searching ROM libraries, launching specific games, and capturing screenshots of active gameplay.
Users interact with the system through the Model Context Protocol or a dedicated CLI client. The setup requires running a daemon on the MiSTer device itself while the MCP server runs on a local machine. It includes specialized tools for hardware management, such as reading and writing core settings, modifying DIP switches, and navigating OSD menus. For secure remote access, the server can manage Tailscale VPN configurations to avoid exposing the unencrypted ClawExec protocol to the open internet.
What you can do with it
- 1Search and launch gamesAn AI agent can find specific titles within your ROM collection and start them immediately.
- 2Modify hardware settingsYou can instruct an agent to change core options or DIP switches to adjust game difficulty or behavior.
- 3Monitor system statusAsk your AI client to check which game is currently running or view hardware details like temperature and uptime.
- 4Remote hardware managementUse the agent to set up a secure VPN connection for accessing your MiSTer from different locations.
Written from the project's README. Every use case is checked against a quote from it.
misterclaw MCP tools 17
Detected from the READMEmister_statusmister_launchmister_searchmister_systemsmister_screenshotmister_infomister_inputmister_osd_infomister_osd_visiblemister_cfg_readmister_cfg_writemister_reload
| mister_status | — | |
| mister_launch | — | |
| mister_search | — | |
| mister_systems | — | |
| mister_screenshot | — | |
| mister_info | — | |
| mister_input | — | |
| mister_osd_info | — | |
| mister_osd_visible | — | |
| mister_cfg_read | — | |
| mister_cfg_write | — | |
| mister_reload | — |
Show all 17 toolsShow fewer tools
mister_osd_navigatemister_system_infomister_rescanmister_tailscalemister_shell
| mister_osd_navigate | — | |
| mister_system_info | — | |
| mister_rescan | — | |
| mister_tailscale | — | |
| mister_shell | — |
Automated checks
Ran Nov 15, 2026Full report →Not verified yet. A server needs a score of 80, no serious finding, and enough data for us to check. How checks work · What to fix for more points
- Source repository linked and reachablecatallo/misterclaw is public and reachablegithub.com/catallo/misterclaw ↗Pass
- Package names this repository as its sourceNot checked
- Build provenance (Sigstore attestation)Not checked
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-10-11github.com/catallo/misterclaw ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNot checked
- No critical advisory in the package or its dependenciesNot checked
- No hidden instructions to the model17 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNo tool named like delete, drop or execPass
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHub👾🦀 MiSTerClaw — MCP Remote Control for MiSTer-FPGA
MiSTerClaw is the first MCP server for MiSTer-FPGA. Control your MiSTer from any AI agent.
(Badge suggestion: thanks, punkpeye.)
v0.8.1 adds validated native ZIP-member launches and an independent GBA2P profile. See the release notes and hardware-test limits, ZIP-member usage, and GitHub Releases for downloads and checksums.
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, read and modify core settings and DIP switches, navigate the OSD menu using conf_str-based position calculation (experimental, not yet reliable for all cores), query detailed system information, manage the system, and even set up Tailscale VPN for secure remote access from anywhere. Floppy-disk cores (PC8801, MSX, etc.) support PostLaunch auto-reset for seamless game loading. 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.
Arcade games
Arcade games are indexed from .mra descriptors and launched directly (initial support: thanks, stt); they are
not represented by the MAME ZIP folder or a single system-wide RBF. Recursive
canonical folders and _alternatives are supported on SD and USB. Generated
_Organized views are omitted when canonical descriptors exist in the same
root; an organized-only collection remains usable as a fallback. Byte-identical
fallback descriptors are deduplicated, while different variants are retained.
Counts describe indexed descriptors/variants, not unique game families. Cache
schema v3 upgrades old v1/v2 Arcade and MAME entries in place while preserving
unrelated cached systems; it does not require a full ROM rescan on upgrade.
A location-specific SD rescan also refreshes _Arcade, and existing SD/USB
Arcade folders are merged rather than replaced. Location rescans now return
status: pending immediately; poll systems.scanning until it becomes false.
Existing results remain available during the refresh. Requests for overlapping
scans or invalid locations fail explicitly. MRA launches validate the file,
recycle virtual input devices, and report the descriptor's requested <rbf> in
core_name; this response is not by itself proof that the FPGA finished loading.
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_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 (initial output-handling fix: thanks, stt) |
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.
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 Client
For agents that have shell access (like OpenClaw, Codex, or Claude Code), the CLI client can be more efficient than MCP — no tool schemas in context, just call it when needed. It's also useful for shell scripts and automation.
# 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
All commands support --json for machine-readable output.
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 |
Downloads and supported platforms
Download executables from GitHub Releases, not from the source repository. The release workflow builds these targets:
| Platform | Architecture | Downloads |
|---|---|---|
| MiSTer | Linux ARMv7 | misterclaw-linux-arm7 daemon |
| Linux | x86-64, ARM64, ARMv7 | CLI and MCP server |
| macOS | Intel x86-64, Apple Silicon ARM64 | CLI and MCP server |
| Windows | x86-64 | CLI and MCP server (.exe) |
Windows downloads are included in v0.8.0 and newer; older releases may not contain them. The daemon runs only on the MiSTer, not on Windows or macOS. On Linux/macOS, make the downloaded client executable with chmod +x <filename>.
For Windows, use the downloaded executable in PowerShell, for example:
.\misterclaw-send-windows-amd64.exe -H mister-fpga status
Point your MCP client's command to the absolute path of misterclaw-mcp-windows-amd64.exe; JSON paths must escape backslashes, for example C:\\Tools\\misterclaw-mcp-windows-amd64.exe.
The release workflow builds tagged releases (initial workflow: thanks, stt). New CI-generated releases include SHA256SUMS and build-metadata.json recording the source commit, compiler version and target inventory. Branch/PR/manual CI runs produce preview artifacts only. Publishing requires a version-tag push from main history and passing tests; maintainers must check release and licensing readiness before pushing a tag. Main ancestry is not itself proof of review approval. Adding CI does not create a new release.
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 results (including full ROM file listings) are cached to disk. First startup scans and builds the cache; subsequent starts load instantly. Use the rescan command after adding new games or drives.
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
misterclaw MCP questions
What tools does misterclaw MCP provide?
It exposes 17 tools, including mister_status, mister_launch, mister_search, mister_systems, mister_screenshot.
Can I control my MiSTer-FPGA remotely?
Yes, MiSTerClaw allows AI agents and CLI clients to control a MiSTer-FPGA over the network, including launching games and managing settings.
Is it secure to use MiSTerClaw over the internet?
You should not expose port 9900 directly to the internet as the protocol lacks authentication and encryption; instead, use Tailscale VPN for secure remote access.
How do I add new games to my library?
After adding new games or drives, you can use the rescan command to update the library.