Skip to main content
Glama

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

Related MCP server: MCP Roku Control

The tools

Tool

Does

Changes anything

mister_status

Whether the MiSTer is on, and the system and game it runs

No

mister_search

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

mister_launch

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

mister_launch_confirm

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

mister_update_request

Checks that update_all may run (512 MB free, none running, the MiSTer up two minutes) and asks, naming a running game

No

mister_update_confirm

The owner's yes, with its one-time token: starts update_all, which may restart the MiSTer

Updates the MiSTer

mister_update_status

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 answer

The 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 most

A 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 it

The 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 fail

CONTRIBUTING.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 tools
mister_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_statusA
Read-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_requestA
Read-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_statusA
Read-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

    A3.7/5.0

    Scored across 7 tools

    Disambiguation5/5

    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'.

    Naming Consistency4/5

    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.

    Tool Count5/5

    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.

    Completeness4/5

    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

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      B
      quality
      A
      maintenance
      Control 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.
      23
      72 PyPI
      58
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      Enables 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.
      14
      MIT