mcp-romm is an MCP server for the RomM self-hosted retro game library manager, allowing you to browse and manage your game library through any MCP-compatible AI assistant.
Purpose
It provides an MCP interface for RomM, enabling AI assistants to query and operate a personal retro game library in natural language, covering scenarios such as browsing data, searching ROMs, viewing metadata, saves, and task queries.
Main capabilities
40 tools in total: 26 read-only tools for browsing platforms, searching ROMs, viewing metadata, collections (normal, smart, and virtual), saves, play activity, and tasks; 14 write tools for managing play status, play sessions, favorites, notes, and collections.
Example queries include:
- "What platforms are in RomM?"
- "Search for Zelda games"
- "Show my backlog"
- "How many ROMs do I have in total?"
- "What was added recently?"
- "Show the saves for Super Metroid"
- "What's in my favorites?"
- "List the firmware files for PlayStation"
- "What tasks are running?"
- "Which devices are registered?"
Write examples include:
- "Mark Chrono Trigger as completed"
- "Favorite Super Metroid"
- "Add to backlog and rate it 9"
- "Create a collection named 'SNES RPGs' and add ROMs 10, 11, and 12"
- "Add a note to this ROM: 'The second boss is buggy, save often'"
Usage
Requires a running RomM instance (v5.0+; most read-only tools also support v4.4+) and an enabled RomM user account, with no admin privileges required. It can be installed by cloning and setting environment variables; it supports being added to Claude Code (e.g. .mcp.json) and Claude Desktop (e.g. ~/Library/Application Support/Claude/claude_desktop_config.json on macOS). It uses stdio transport by default, and can also be hosted as a remote HTTP service: after setting the environment variables, point the client at that service, for example Claude Code. The HTTP transport has no built-in authentication and can only be bound to a trusted network (LAN, VPN, or Tailscale and other overlay networks), never expose it to the open internet; note that the claude.ai web/mobile connectors initiate connections from Anthropic's cloud and cannot access private network URLs.
Authentication and Security
The server uses OAuth2 password grant with RomM authentication. Tokens request only the minimum scopes needed, including read-only scopes plus roms.user.write, collections.write, and tasks.run; it does not request roms.write, platforms.write, firmware.write, assets.write, users.write, or me.write. Write tools only modify the user's own data (play status, favorites, notes) and their own collections; no tool edits ROM files, platforms, firmware, other users, or uploads/deletes save files. Destructive operations are clearly marked: romm_delete_note and romm_delete_collection permanently delete data; romm_delete_collection only deletes the grouping, not the ROM. Credentials and tokens are kept in memory only and are not written to disk. TLS certificate verification is enabled by default (ROMM_TLS_VERIFY=true). When a token expires, it automatically re-authenticates and retries once.
Use Cases
Suitable for users who want to query and manage their personal RomM game library conversationally with an AI assistant, especially for deployment in a home lab or trusted network, for browsing platforms, searching ROMs, viewing metadata, managing collections and notes, tracking play status, and more.
Limitations and Known Issues
- Requires a running RomM instance (v5.0+; most read-only tools support v4.4+) and an enabled user account; romm_scan_library requires an account with permission to run tasks.
- RomM 5.0 merges the old viewer/editor/admin roles into user/admin and switches to a permission system; if a 403 occurs on a 5.0 instance, check the account's effective permissions (GET /api/permissions/me).
- RomM 5.0.0 server-side issues: romm_filters times out (the query forms a Cartesian product, the request hangs and the server keeps running at high CPU, so it should be avoided); once a note exists, the note list returns 500 (creatingand deleting notes works normally, but romm_rom_notes and reading back after romm_add_note will error); library scans cannot be triggered via REST (scan_library is marked manual_run: false, POST /api/tasks/run/scan_library is rejected; romm_scan_library will report this situation, and scans run on schedule or from the Web UI).
- The license is MIT.
