mister-mcp
You can use this server to inspect and control a MiSTer through Zaparoo: check status, find games, launch games/cores, and manage update_all.
Check whether the MiSTer is on and what system/game it is running.
Search for games by title words; results include region info and follow configured version/region rules.
Launch a game by name or start a system core; if a game/core is already running, ask first and require confirmation with a one-time token.
After launching, optionally show the MiSTer on a configured TV if the TV is already on.
Request an update_all update after precondition checks, confirm it with a one-time token, and check update progress/result.
Responses include speakable
saytext and structured success/outcome data.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@mister-mcp launch Super Metroid"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
mister-mcp
Start retro games on a MiSTer FPGA by voice: an MCP server and claude-voice plugin.
It is a small MCP server over stdio, and an optional plugin for claude-voice. It talks to Zaparoo Core, which runs on the MiSTer, and sends it only the calls listed in ADR-MM-001. No tool writes, deletes or changes anything on the MiSTer.
Try it without a MiSTer
--simulate answers from a pretend MiSTer, and says so:
$ uv run mister-mcp status --simulate
Simulated: The MiSTer is on, at its menu.Pairing with a secured Zaparoo, against a pretend one that saves nothing:
$ uv run mister-mcp pair --simulate
Simulated: Paired with the MiSTer. Nothing was saved.The server itself, as a voice session starts it; it ends when its input does:
$ uv run mister-mcp serve --simulate < /dev/nullRelated MCP server: MCP Roku Control
The tools
Tool | Does | Changes anything |
| Whether the MiSTer is on, and the system and game it runs | No |
| Five games at a time whose names hold every word said, on one system when one is named, each with its region; hacks and other such versions only when all versions are asked for | No |
| Starts a game by name, in a region when one is named and otherwise the clean cartridge in the owner's region order, or a system's core alone; reads back what runs, then shows it on the TV if that TV is already on. While a game runs, it asks first | Starts a game |
| The owner's yes to that question, with its one-time token: ends the running game and starts the one asked for | Starts a game |
| Checks that update_all may run (512 MB free, none running, the MiSTer up two minutes) and asks, naming a running game | No |
| The owner's yes, with its one-time token: starts update_all, which may restart the MiSTer | Updates the MiSTer |
| Whether update_all runs, its current step and about how long is left, or how it ended | No |
Every answer has say, read aloud as it is, and success with outcome
for a program: done, unreachable (the MiSTer did not answer: off, or not
on the network), not_found, refused, or working (still going after the
voice's time, and carrying on), or ask (a question to read aloud, with a
token for the yes).
Which actions are risky is the owner's call (the plugin standard's rule 7).
Starting a game from the menu is not. Ending a running game is: a launch
while a game or core runs is a question that names what runs, and only
mister_launch_confirm with its token, within a minute, starts the new one.
Switching the MiSTer's power through a smart plug will be risky too; it is not
built yet.
update_all runs over SSH by key only, and only commands from a fixed list
are ever sent (ADR-MM-004).
The key the MiSTer accepts sits alone in ~/.config/mister-mcp/ssh-key.
Settings
In ~/.config/mister-mcp/config.toml, never in this repository:
[mister]
address = "mister.example" # the MiSTer's name on the home network
addresses = ["192.0.2.10"] # optional spares, tried in order when the name does not answerThe name is tried first, then each spare. Together they take at most six
seconds, so the voice still gets its answer in time. After that, the address
that answered is asked first. mister_status says which address it used.
When none of them answers, the voice names each one and says what to check.
When a game exists in several versions, the voice hears the clean cartridge first, then the others, in the owner's region order:
[search]
region_order = ["eu", "world", "us", "jp"] # any of the four, first the one wanted mostA region the list leaves out comes after it, in the order world, USA, Europe,
Japan. Anything but those four refuses to start, naming the setting. Hacks,
pirate and trained copies, translations, PlayChoice-10 arcade versions, and an
alternate dump beside a clean one, are heard only when the owner asks for all
versions. They are read from the file name as No-Intro and GoodTools write it
((Europe), (USA, Europe), (E), (JU), [a1], [h1], [T+Eng], [!]).
Without region_order, the order comes from the locale (LC_ALL, then
LANG): a European country, nb_NO among them, puts Europe first, en_US
the USA, ja_JP Japan. The claude-voice bridge starts plugins without a
locale, so under it an unset order is world, USA, Europe, Japan. Set
region_order to have it otherwise. The server says which order it uses when
it starts, for example region_order unset and no locale given: using world, us, eu, jp.
To have the TV the MiSTer is plugged into show it after a start, add the TV plugin (tv-mcp) and the names it knows:
[tv]
command = ["uv", "run", "--directory", "~/tv-mcp", "tv-mcp", "serve"]
name = "the den" # the TV, as tv-mcp knows it
device = "MiSTer" # the device on its input, as tv-mcp's settings name itThe plugin starts that server for a moment, asks tv_status whether the
screen is on, and only then asks tv_input to show the device. It calls no
other TV tool, and closes the TV plugin again after each start
(ADR-MM-002).
A Zaparoo API key, if Zaparoo is set to ask for one, goes alone in
~/.config/mister-mcp/zaparoo-key, readable by the owner only
(chmod 600); the plugin refuses a key file others can read.
The gates
Every one of these runs in continuous integration, and all of them run here:
$ uv run ruff check .
All checks passed!uv run ruff format --check . # layout
uv run mypy src # types
uv run pytest -q # behaviour
python scripts/mutate.py # that each rule's own test can failCONTRIBUTING.md says what each one is for, and
decisions/ records the choices that shaped them,
including how a change is made here.
Licence
GPL-3.0-or-later. See LICENSE.
Available Tools
7 toolsmister_launchB
Start a game or a core. Game: words of its title. System: its name, alone to start its core with no game. Then the TV it is plugged into shows it, only if that TV is already on.
Inputs: game, system. Returns: object
mister_launch_confirmA
Say yes to a start. Only after the owner clearly said yes to the question mister_launch asked. Token: the one that question gave.
Inputs: token (required). Returns: object
mister_searchBRead-only
Find a game by its name. Name: words from the game's title, as the owner said them.
Inputs: name (required). Returns: object
mister_statusARead-only
What is it playing? Whether the MiSTer is on, and the system and game it runs.
Inputs: no named parameters. Returns: object
mister_update_confirmA
Go ahead with update_all. Only after the owner clearly said yes to the question mister_update_request asked. Token: the one that question gave.
Inputs: token (required). Returns: object
mister_update_requestARead-only
Update the MiSTer with update_all. Asks first and starts nothing: checks the free space and names a running game. Read its question aloud.
Inputs: no named parameters. Returns: object
mister_update_statusARead-only
How is the update going? Whether update_all runs, its current step, and how it ended.
Inputs: no named parameters. Returns: object
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 7 tools
Each tool targets a distinct action+resource: status (playback state), search (find game), launch/launch_confirm (start with token gating), update_request/update_confirm/update_status (update lifecycle). The token-based confirm tools are explicitly tied to their request counterparts, and mister_status vs mister_update_status are clearly separated by 'playing' vs 'update progress'.
All tools share the mister_ prefix and snake_case, with the update_* family (request/confirm/status) and launch/launch_confirm forming a predictable request-confirm pattern. Minor inconsistency in that some names are bare actions (status, search) while others are compound, but overall readable and coherent.
Seven tools is well-scoped for controlling a MiSTer device: query, search, launch flow, and update flow. Each tool earns its place, and the split of launch/update into request+confirm+status is justified by the safety-confirmation design.
Core workflows (status, search, launch, update with confirmation and progress) are well covered. However, there is no explicit way to stop a running game or power off the device, which are notable gaps for a gaming-device controller, though launching a bare core may work around stopping.
Maintenance
Related MCP Connectors
Hosted MCP server connecting AI assistants to 9,000+ apps and 40,000+ actions via Zapier.
Control Android TV from any AI. 38 MCP tools: playback, recap, recommend, smart-home, schedules.
Manage ZAP-Hosting game servers, VPS, dedicated servers, TeamSpeak and domains from your AI client.
Manage digital signage screens, playlists and media from your AI assistant.
Related MCP Servers
- AlicenseBqualityAmaintenanceControl any smart TV with natural language — play Netflix/YouTube/Spotify by name, cast URLs, scene presets, multi-room audio, and multi-TV sync. Supports LG, Samsung, Android TV, Roku.2372 PyPI58MIT
- FlicenseAqualityDmaintenanceEnables AI assistants to control Roku TVs on the local network via natural language commands.6-
- FlicenseBqualityDmaintenanceEnables discovery and control of smart appliances (TVs, media devices) on the local network through natural language, supporting providers like Roku, Google TV, and Home Assistant.18-
- AlicenseAqualityBmaintenanceEnables users to drive one or more networked retro gaming devices through natural language: finding and launching games, viewing what's playing and play history, taking screenshots, backing up saves, editing configuration settings, writing or mapping NFC cards, and triggering system updates. Actions are host-aware, dry-runnable, and safety-checked, so it refuses to guess which device is meant or to disturb a game already running.14MIT