romm_activity
Get recent activity feed — ROM plays, saves, screenshots, notes. Optionally filter by ROM ID.
LABSCO SUMMARY
Two independent brakes sit in front of anything that writes.
ROMM_READ_ONLY=1 turns the whole server into a browse-only surface — every create, update and delete refuses at the server rather than trusting the client to behave — which is the setting for an agent that is not entirely yours. Separately, deletions need confirm_delete: true on the call itself, so a host that ignores tool annotations still cannot drop a collection by accident. What this adds over the RomM web UI is the ability to ask across the whole library — which platforms carry the most unmatched files, what has been played this week — rather than clicking through pages to find out.
What it is
An MCP server for RomM, the self-hosted game and ROM management platform. It browses and searches the library, reads full ROM metadata, manages collections and notes, and lists saves, states, screenshots and firmware. Both stdio and Streamable HTTP transports are supported, so it runs locally or in Docker for remote clients.
What you get
- romm_browse_roms pages and filters by platform, collection, favourites or unmatched with sorting; romm_search_roms finds a game by name and romm_get_rom returns the full record with genres, companies, file info and notes
- romm_list_platforms gives every platform with its ROM count and metadata, and romm_stats totals platforms, ROMs, saves, states, screenshots and overall file size
- romm_manage_collections lists, gets, creates, updates and deletes collections including smart and virtual ones, and romm_get_collection_roms reads what is inside one
- romm_update_rom edits name, notes and favourite status, and romm_rom_notes lists, adds, updates and deletes the notes attached to a ROM
- romm_manage_saves, romm_manage_states and romm_screenshots list files filtered by ROM, romm_list_firmware lists firmware by platform, and romm_download_rom returns a download URL
- romm_activity is the recent feed of plays, saves, screenshots and notes, and romm_system covers the heartbeat check and config; on RomM 5.0 its scan and metadata-refresh actions only point you to Settings → Tasks in the web UI
- Every tool carries MCP annotations — readOnlyHint on browsing and listing, destructiveHint on anything that deletes, idempotentHint on create and update — so a compliant host can prompt before the risky ones
Requirements
Node.js 20 or newer and a RomM instance at v5.0 or later. ROMM_BASE_URL and ROMM_API_KEY are both required, with the rmm_ token generated in RomM under Settings → API Keys. Run it as npx romm-mcp over stdio, or set MCP_TRANSPORT=http with MCP_PORT (default 3000) and MCP_HOST (default 0.0.0.0) for Streamable HTTP, which is what the bundled Docker setup uses. ROMM_READ_ONLY=1 refuses every mutating tool at the server itself, and deletions additionally require confirm_delete: true on the call. ROMM_DEBUG=1 turns on debug logging.
Setup effort
One command plus a key — npx romm-mcp, then supply credentials
USE CASES
01
Finding a game you know you own somewhere
Search by name across every platform, then open the full record with its genres, companies, file details and any notes you left on it.
02
Getting a picture of the whole library
Totals for platforms, ROMs, saves, states, screenshots and file size, with per-platform counts underneath them.
03
Tidying a collection that has grown untidy
Filter for the unmatched or unfavourited entries, build a collection from what you find, and correct names and notes as you go.
04
Picking up where you left off
The recent activity feed of plays, saves and screenshots, and the save states attached to whichever game you were last in.
05
Letting an agent browse without letting it change anything
Start the server in read-only mode and every mutating tool refuses at the server, independent of what the client decides to allow.
16 tools
Counted once with only startup setup. Other versions, modes or optional credentials may expose a different list.
romm_browse_roms
Browse and filter ROMs with pagination. Supports filtering by platform, collection, favorites, unmatched, and sorting.
romm_download_rom
Get the download URL for a ROM file.
romm_get_collection_roms
Get all ROMs in a specific collection with details.
romm_get_rom
Get full details for a specific ROM by ID — metadata, genres, companies, file info, notes.
romm_list_firmware
List firmware files available in RomM, optionally filtered by platform.
romm_list_platforms
List all platforms in the RomM library with ROM counts, categories, and metadata.
romm_manage_collections
Manage RomM collections. Actions: list, get, create, update, delete. Also supports smart and virtual collections.
romm_manage_saves
List save files, optionally filtered by ROM.
romm_manage_states
List save state files, optionally filtered by ROM.
romm_rom_notes
Manage notes attached to a ROM. Actions: list, add, update, delete.
romm_screenshots
List screenshots, optionally filtered by ROM.
romm_search_roms
Search ROMs by name. Returns matching ROMs with basic info. Use this to find specific games.
romm_stats
Get RomM library statistics — total platforms, ROMs, saves, states, screenshots, and total file size.
romm_system
System operations: heartbeat check, get config, trigger library scan, or update metadata.
romm_update_rom
Update ROM metadata — name, notes, favorite status.
BEFORE YOU INSTALL
What to know first
Tools you get
16 tools when we connected. ROMM_READ_ONLY=1 makes every create, update, delete and scan tool refuse, and deletes also need confirm_delete: true. Against RomM 5.0, the scan and metadata_scan actions of romm_system no longer work.
Requires
- npx on PATH
- Node.js >= 20.0.0
- ROMM_API_KEY in your environment
CONTEXT COST
Light Standing cost
Rated by the size of the 16 tool definitions that ride along on every turn, not by how many there are
INSTALLATION
Connect your client
Server setup
TERMINAL
npx romm-mcpMCP Clients
Claude Desktop
CLAUDE DESKTOP · JSON
{
"mcpServers": {
"romm": {
"command": "npx",
"args": [
"-y",
"romm-mcp"
],
"env": {
"ROMM_BASE_URL": "http://<YOUR_ROMM_INSTANCE>:5500",
"ROMM_API_KEY": "<YOUR_ROMM_API_KEY>"
}
}
}
}CoPaw, OpenClaw
JSON
{
"mcpServers": {
"romm": {
"name": "romm",
"description": "RomM MCP server",
"enabled": true,
"transport": "stdio",
"command": "npx",
"args": [
"-y",
"romm-mcp"
],
"env": {
"ROMM_BASE_URL": "http://<YOUR_ROMM_INSTANCE>:5500",
"ROMM_API_KEY": "<YOUR_ROMM_API_KEY>"
}
}
}
}Any MCP client — HTTP
Start the server in HTTP mode first — it listens on port 3000:
ANY MCP CLIENT — HTTP · TERMINAL
MCP_TRANSPORT=http MCP_PORT=3000 \
ROMM_BASE_URL=http://<YOUR_ROMM_INSTANCE>:5500 \
ROMM_API_KEY=<YOUR_ROMM_API_KEY> \
npx romm-mcpThen connect your client:
ANY MCP CLIENT — HTTP · JSON
{
"mcpServers": {
"romm": {
"type": "streamable-http",
"url": "http://localhost:3000/mcp"
}
}
}Clients spell the "type" value differently: Claude Code and VS Code use "http", Cline uses "streamableHttp", and Roo Code uses "streamable-http". Claude Desktop does not accept a URL entry in its config file.
Any MCP client — Docker
Run the published image — it starts in HTTP mode on port 3000:
ANY MCP CLIENT — DOCKER · TERMINAL
docker run -d --name romm-mcp -p 3000:3000 -e ROMM_BASE_URL=http://host.docker.internal:5500 -e ROMM_API_KEY=<YOUR_ROMM_API_KEY> ghcr.io/rodrigosiviero/romm-mcp:mainThen connect your client:
ANY MCP CLIENT — DOCKER · JSON
{
"mcpServers": {
"romm": {
"type": "streamable-http",
"url": "http://localhost:3000/mcp"
}
}
}Clients spell the "type" value differently: Claude Code and VS Code use "http", Cline uses "streamableHttp", and Roo Code uses "streamable-http". Claude Desktop does not accept a URL entry in its config file.
