RomM MCP Server

An MCP server for RomM — the self-hosted retro game library manager. 92 tools: 50 read-only for browsing platforms, searching ROMs, viewing metadata, collections (regular, smart, and virtual), saves and states, soundtracks, play activity, recommendations, memory cards, notifications, devices, audit events and tasks — plus 42 write tools for play status, play sessions, favorites, notes, collection management, music playlists, emulator-streaming sessions and, behind opt-in tiers, notifications, device installs and save/state/memory-card housekeeping, through any MCP-compatible AI assistant.

Tracks RomM 5.0 through 5.4. Features added after 5.0 are version-gated against /api/heartbeat and explain themselves on an older server instead of returning a bare 404. Every tool carries MCP annotations (readOnlyHint / destructiveHint / idempotentHint), so a client can tell a browse from a delete without guessing.

Tools

Read

Write

These modify your own user data, collections, and music playlists. They cannot alter ROM files, platforms, firmware, other users, or RomM save files.

The exception is the emulator-streaming cluster, which starts and stops a server-side emulator container and can write that emulator's own save states. Those are separate from RomM's battery-save files, which no tool here touches.

Opt-in write tiers

The tools below are present but refuse until their tier is enabled with ROMM_WRITE_TIERS (comma-separated: notifications, devices, assets). Each tier adds one scope to the token — me.write, devices.write, assets.write — and each widens the blast radius beyond "your own play data and collections", so none is requested by default. romm_status shows which tiers are on and whether RomM granted them.

Not implemented on purpose

RomM exposes more than this server wraps. Outside its boundary, by design: deleting ROM files (DELETE /api/roms/{id}/files/{id}), rewriting scan or converto settings, uploading ROMs or creating physical/identity edits, uploading manuals, walkthroughs, screenshots or soundtrack files, uploading or downloading memory-card images and save files (binary traffic, not chat material), and the notification API's ability to target other users. None of those has a tool, and roms.write, platforms.write, firmware.write and users.write are never requested.

Related MCP server: proxy-mcp

Setup

Prerequisites

• Python 3.10+

• A running RomM instance (v5.0–v5.4; most read tools also work on v4.4+)

• An enabled RomM user account — admin is not required (see Auth)

Install

pip install fastmcp httpx

Or clone and install:

git clone https://github.com/lodordev/mcp-romm.git
cd mcp-romm
pip install .

Configure

Set environment variables:

Add to Claude Code

Add to your .mcp.json:

{
  "mcpServers": {
    "romm": {
      "command": "python",
      "args": ["/path/to/mcp-romm/server.py"],
      "env": {
        "ROMM_URL": "http://your-romm-instance:3000",
        "ROMM_USERNAME": "your-username",
        "ROMM_PASSWORD": "your-password"
      }
    }
  }
}

Add to Claude Desktop

Add to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "romm": {
      "command": "python",
      "args": ["/path/to/mcp-romm/server.py"],
      "env": {
        "ROMM_URL": "http://your-romm-instance:3000",
        "ROMM_USERNAME": "your-username",
        "ROMM_PASSWORD": "your-password"
      }
    }
  }
}

Remote (HTTP) transport

By default the server speaks stdio and is spawned by the client. To host it as a shared network service instead — e.g. one instance on your homelab that all your machines use — set:

ROMM_MCP_TRANSPORT=http ROMM_MCP_HOST=0.0.0.0 ROMM_MCP_PORT=8765 python server.py

Then point clients at it, e.g. Claude Code:

claude mcp add --transport http romm http://your-host:8765/mcp

The HTTP transport has no authentication of its own — bind it to a trusted network only (LAN, VPN, or an overlay network like Tailscale), never the open internet. Note that claude.ai web/mobile connectors connect from Anthropic's cloud and cannot reach private-network URLs.

"Trusted network" is weaker than it sounds: a web page open in a browser on any machine that can reach the port can target it through DNS rebinding, because FastMCP validates Host/Origin only for loopback binds by default. Set ROMM_MCP_ALLOWED_HOSTS to the exact host values your clients use (ROMM_MCP_ALLOWED_HOSTS=100.64.0.9) and FastMCP rejects everything else.

Examples

Once configured, you can ask your AI assistant things like:

• "What platforms do I have in RomM?"

• "Search for Zelda games"

• "Show me my backlog"

• "How many ROMs do I have total?"

• "What was recently added?"

• "Show me the saves for Super Metroid"

• "What's in my favorites?"

• "List my firmware files for PlayStation"

• "What tasks are running?"

• "What devices are registered?"

And, with the write tools:

• "Mark Chrono Trigger as finished"

• "Favorite Super Metroid"

• "Add it to my backlog and rate it 9"

• "Make a collection called 'SNES RPGs' and add ROMs 10, 11, and 12"

• "Add a note to this ROM: 'glitch at the second boss, save often'"

• "Pick me something random to play on the SNES"

• "What soundtrack albums do I have by Nobuo Uematsu?"

• "Make a playlist called 'Focus' and add those tracks"

• "Launch Shadow of the Colossus in the streaming emulator"

• "What should I play next, and why?"

• "Anything in my RomM inbox?"

• "Send Chrono Trigger to my handheld" (with ROMM_WRITE_TIERS=devices)

• "Label that save 'before final boss'" (with ROMM_WRITE_TIERS=assets)

Security

• Least privilege. The OAuth2 token requests only the read scopes the tools use plus roms.user.write and collections.write, and negotiates for the two optional tiers (tasks.run, and playlists.read/playlists.write on 5.1+). It never requests roms.write, platforms.write, firmware.write, or users.write.

• Opt-in write tiers. me.write, devices.write and assets.write are requested only when you list their tier in ROMM_WRITE_TIERS. me.write also lets a token edit the account's own profile in RomM, which is exactly why notifications are off until you turn them on.

• Read-only kill switch. ROMM_READ_ONLY=true does two things: the HTTP helper refuses every non-GET API call regardless of which tool was called, and the token is requested with no *.write scope and no tasks.run, so the credential a read-only process holds cannot write even if it leaked. (The OAuth grant itself is still a POST to /api/token.)

• Bounded write surface. Write tools change only your own user data (play status, favorites, notes, music favourites and playlists, notifications, save/state metadata) and your own collections and devices. No tool edits ROM files, platforms, firmware, other users, or uploads/downloads/deletes RomM save files or memory-card images.

• Untrusted text stays in its field. ROM names and summaries (from metadata providers), notes, collection and playlist descriptions, notification bodies, labels, channel names, audit targets and other users' names are rendered with control characters, bidi overrides, zero-width and Unicode tag characters stripped, newlines collapsed and length capped, so content written by someone else can't masquerade as tool output. This keeps text visibly inside its field; it does not try to judge what the text says. Channel targets and secrets are shown masked and never echoed back.

• Webhooks can't point inward. With the notifications tier on, RomM becomes an outbound HTTP client for whatever webhook URL a tool call supplies, so loopback, private, link-local and bare internal hostnames are refused, and notification links must be a RomM path or an http(s) URL.

• No ownership checks of its own. Deletes and dismissals by ID rely on RomM's authorization — this server never sees whose object an ID is. Keep the account's grants scoped (RomM's permission groups) if "your own data only" matters to you.

• Emulator streaming is the one broader surface. romm_streaming_* starts and stops a server-side emulator container and can write that emulator's save states. romm_streaming_stop kills a running emulator and is annotated destructive. Nothing here touches RomM's own save files.

• Destructive ops are labeled. Every tool that permanently removes data says so in its description and carries destructiveHint. Collection and playlist deletes remove the grouping, never the ROMs or audio.

• No disk writes. Credentials and tokens are held in memory only, never written to disk. The password can come from a file (ROMM_PASSWORD_FILE) rather than the environment.

• TLS by default. Certificate verification is enabled by default (ROMM_TLS_VERIFY=true).

• Auto-retry. If a token expires mid-session, the server re-authenticates transparently.

Auth

The server uses OAuth2 password grant to authenticate with RomM. Tokens are automatically refreshed when they expire, and a 401 triggers one transparent re-authenticate-and-retry.

Scopes are negotiated, not assumed. RomM's token endpoint rejects the entire request with 403 Insufficient scope if any single requested scope falls outside the account's set — so asking for a scope your server or account doesn't have would take down every tool, not just the ones that need it. On first authentication this server asks for everything it wants; if that is refused it establishes that the core set works, then probes each optional tier once and drops the ones refused. The result is cached for the process, so token expiry doesn't re-run the probe. romm_status reports what was granted and what was dropped, and any tool needing a dropped tier says so plainly.

This matters in two common cases:

• RomM 5.0 servers, where playlists.* does not exist at all.

• Least-privilege service accounts, which typically lack the admin-tier tasks.run.

Note: The read and write tools operate on your own library and user data, so an ordinary enabled RomM user account is sufficient — admin is not required. (romm_scan_library needs an account permitted to run tasks; romm_streaming_sessions is admin-only on RomM's side and says so.)

RomM 5.0 role change: RomM 5.0 collapsed the old viewer/editor/admin roles into user/admin and moved fine-grained authorization to a permissions system (legacy roles are coerced to user on upgrade). If a tool unexpectedly gets a 403 on a 5.0 instance, check the account's effective permissions (GET /api/permissions/me) in the RomM admin UI.

Version support

The 5.3 and 5.4 tools were built against RomM's tagged source and the live 5.4.1 OpenAPI schema (routes, request bodies, response shapes, and scope requirements). Every new tool has request-shaping unit tests, and the suite was run live against RomM 5.4.1 as a least-privilege account (82 of 83 live checks passing; the one miss was a scan refused because another scan was already running, which the tool now explains). The API surface is purely additive from 5.0.0 through 5.4.1 — routes were added, none removed or changed — so nothing that worked on an older server is at risk. smoke_test.py exercises the read side of each new cluster live where the server has data for it; per-card and per-session detail tools need an existing card or session and are unit-tested instead.

Known issues

On RomM 5.4.1 none of these reproduce: the live suite passes 83 of 83 checks against a 5.4.1 instance as a least-privilege account (notes list, filters endpoint and REST-triggered scans all work). The items below are kept for anyone still on 5.0.0, where they were found by running smoke_test.py:

• romm_filters times out. GET /api/roms/filters in RomM 5.0.0 executes a query with a cartesian product (RomM's log flags it at roms_handler.py:2159); the request hangs until the client timeout, and the abandoned query keeps running server-side at high CPU. Avoid calling romm_filters on 5.0.0 until this is fixed upstream — every call strands another runaway database query.

• Note listing 500s once any note exists. RomM 5.0.0's GET /api/roms/{id}/notes fails serialization (UserNoteSchema validation in endpoints/roms/notes.py) whenever the ROM has at least one note. Creating and deleting notes work; romm_rom_notes (and the read-back after romm_add_note) will error until fixed upstream.

• Library scans can't be triggered over REST. RomM 5.0.0 flags scan_library as manual_run: false, so POST /api/tasks/run/scan_library is rejected. romm_scan_library reports this instead of failing; scans run on the configured schedule or from the web UI.

License

MIT. See CHANGELOG.md for release history.