# lodordev/mcp-romm [Health: Active]

**Category:** 🎮 Gaming  
**Repository:** https://github.com/lodordev/mcp-romm  
**GitHub Stars:** 5  
**Views:** 3  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/lodordev-mcp-romm

## Description
MCP server for RomM retro game library manager. 19 read-only tools for browsing platforms, searching ROMs, viewing metadata, managing collections, tracking saves, firmware, devices, and task monitoring. OAuth2 auth with automatic token refresh.

## Tools
Capabilities this server exposes over MCP:

- **romm_status** — Check server configuration and reachability
- **romm_stats** — Library-wide statistics (platforms, ROMs, saves, total size)
- **romm_platforms** — List platforms with ROM counts and sizes
- **romm_library_items** — Browse ROMs with filtering and pagination
- **romm_recent** — Recently added or updated ROMs
- **romm_get_item** — Full ROM detail — metadata, saves, user status
- **romm_search** — Search ROMs by name
- **romm_search_by_hash** — Identify a ROM by file hash (CRC, MD5, SHA1, or RetroAchievements)
- **romm_filters** — Available filter values (genres, regions, languages, tags)
- **romm_collections** — List user-curated collections
- **romm_collection_detail** — List ROMs in a specific collection
- **romm_smart_collections** — List auto-generated smart collections
- **romm_saves** — List save files by ROM or platform
- **romm_user_profile** — Browse by status (now playing, backlog, completed, etc.)
- **romm_rom_notes** — View notes on a ROM
- **romm_firmware** — List BIOS/firmware files per platform
- **romm_devices** — List registered devices
- **romm_tasks** — List registered tasks (schedule, manual-run availability) and running status
- **romm_scan_library** — Trigger a background library rescan (blocked over REST on RomM 5.0 — see Known issues)
- **romm_activity** — Recent play activity feed — who played what, when (5.0+)
- **romm_play_sessions** — List recorded play sessions with durations (5.0+)
- **romm_virtual_collections** — Automatic groupings by genre/franchise/company/etc. (5.0+)
- **romm_virtual_collection_detail** — List ROMs in a virtual collection (5.0+)
- **romm_smart_collection_detail** — A smart collection's rules and matching ROMs (5.0+)
- **romm_whoami** — Authenticated account, role, and effective permissions
- **romm_metadata_search** — Search metadata providers (IGDB etc.) for ROM matches (5.0+)
- **romm_set_status** — Set play status, backlog, now-playing, rating, completion, last-played
- **romm_favorite** — Add or remove a ROM from your favorites
- **romm_add_note** — Add a note to a ROM
- **romm_update_note** — Edit an existing note
- **romm_delete_note** — Delete a note (permanent)
- **romm_create_collection** — Create a new collection
- **romm_add_to_collection** — Add ROMs to a collection
- **romm_remove_from_collection** — Remove ROMs from a collection
- **romm_delete_collection** — Delete a collection — the grouping only, not the ROMs (permanent)
- **romm_log_play_session** — Record a play session on a ROM (5.0+)
- **romm_delete_play_session** — Delete one of your play sessions (permanent, 5.0+)
- **romm_create_smart_collection** — Create a smart collection — a saved filter that auto-matches ROMs (5.0+)
- **romm_update_smart_collection** — Edit a smart collection's name/description/rules (5.0+)
- **romm_delete_smart_collection** — Delete a smart collection — the saved filter only (permanent, 5.0+)

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `uvx` (confidence: high):

```json
"mcpServers": {
  "mcp-romm": {
    "command": "uvx",
    "args": ["fastmcp"],
    "env": {
      "ROMM_USERNAME": "",
      "ROMM_PASSWORD": ""
    }
  }
}
```

**Requires environment variables:** `ROMM_USERNAME`, `ROMM_PASSWORD` — the values above are empty placeholders; fill in real credentials before running (see the repository for what each one is for).

## Documentation

## What lodordev/mcp-romm MCP server does

The lodordev/mcp-romm MCP server gives an MCP-compatible AI assistant access to a self-hosted RomM retro game library. It supports library discovery, ROM search, metadata lookup, platform statistics, recently changed items, save-file listings, firmware records, registered devices, tasks, and authenticated user details.

Its tools also cover several collection types, including user-created, smart, and virtual collections. On RomM 5.0 or newer, the server can expose play activity, recorded play sessions, metadata-provider searches, and additional collection operations. A compatible assistant can use the server for questions such as finding a game, checking a backlog, identifying a ROM by CRC, MD5, SHA1, or RetroAchievements hash, or reviewing a library’s overall size.

## How it works

The server communicates with RomM over its API and uses OAuth2 password-grant authentication. It requests scopes for the operations it supports, keeps credentials and tokens in memory, and retries authentication once after an expired-token response. An enabled ordinary RomM user account is sufficient for most operations; administrator access is not generally required.

Read operations cover browsing and inspection. Write operations are limited to the authenticated user’s data and collections. They can set play status, backlog and rating values, manage favorites and notes, create or modify collections, and record or remove personal play sessions where supported. They cannot edit ROM files, platforms, firmware, other users, or save files.

## Setup and configuration

The lodordev/mcp-romm MCP server requires Python 3.10 or newer and a running RomM instance. Most read tools also support RomM 4.4 or later, while the project’s stated target is RomM 5.0 or newer. Install the project from its repository after installing its Python dependencies, then start `server.py` through an MCP client or directly.

Set `ROMM_USERNAME` and `ROMM_PASSWORD` for the RomM account. `ROMM_URL` defaults to `http://localhost:3000`. Optional settings control normal and long request timeouts, TLS certificate verification, and transport behavior. The default transport is stdio; HTTP mode can bind to a configured host and port for clients on a trusted network.

The README documents configuration examples for Claude Code and Claude Desktop. HTTP transport does not provide its own authentication, so it should not be exposed directly to the public internet.

## Tools and capabilities

- Inspect RomM reachability, account identity, permissions, library totals, platforms, and tasks.
- Search and filter ROMs, browse paginated results, inspect full item metadata, and identify files by hash.
- Browse regular, smart, and virtual collections, including their rules and matching ROMs.
- Review saves, firmware, devices, notes, user status, recent activity, and play sessions.
- Update personal status, ratings, favorites, notes, collections, and supported play-session records.
- Trigger a background library scan when the RomM account and server version allow it.

## Limitations and notes

The lodordev/mcp-romm MCP server does not provide a general ROM-management interface: its write surface excludes ROM files, platforms, firmware, assets, users, and save-file uploads or deletion. RomM 5.0 permissions can cause a 403 response if the account lacks an operation’s effective permission. The library-scan operation is blocked over the REST API on RomM 5.0. The README also identifies RomM 5.0 server-side issues affecting some endpoints, including a timeout for the filters request. Features marked 5.0+ are not available against older RomM versions.

_Full upstream README: https://allmcps.com/mcp/lodordev-mcp-romm/readme_