mcp-romm
The mcp-romm server provides 19 tools to browse, search, and manage a self-hosted RomM retro game library through any MCP-compatible AI assistant.
Check server status (
romm_status): Verify server configuration and reachabilityView library statistics (
romm_stats): Get platform count, ROM count, saves, and total storage sizeList platforms (
romm_platforms): Browse all platforms with ROM counts and sizesBrowse ROMs (
romm_library_items): Filter by platform, search term, or favorites with pagination and sortingView recent ROMs (
romm_recent): See recently added or updated ROMsGet ROM details (
romm_get_item): Retrieve full metadata, user status, and save files for a specific ROMSearch ROMs (
romm_search): Search by name across the entire library or within a platformIdentify ROMs by hash (
romm_search_by_hash): Look up a ROM using CRC32, MD5, or SHA1 file hashesGet filter options (
romm_filters): Retrieve available genres, regions, languages, and tagsList collections (
romm_collections): View user-curated ROM collectionsView collection details (
romm_collection_detail): List all ROMs within a specific collectionList smart collections (
romm_smart_collections): Browse auto-generated, rule-based collectionsView save files (
romm_saves): List save files filtered by ROM or platformBrowse by user status (
romm_user_profile): View ROMs by status — favorites, now playing, backlog, wishlist, completed, or retiredView ROM notes (
romm_rom_notes): Read notes attached to a specific ROMList firmware/BIOS files (
romm_firmware): Browse BIOS and firmware files, optionally filtered by platformList devices (
romm_devices): View registered handhelds, emulators, and other devicesCheck tasks (
romm_tasks): Monitor running and scheduled background task statusTrigger library rescan (
romm_scan_library): Initiate a background rescan to discover new ROMs and platforms
RomM MCP Server
An MCP server for RomM — the self-hosted retro game library manager. 19 read-only tools for browsing platforms, searching ROMs, viewing metadata, managing collections, tracking saves, and monitoring tasks through any MCP-compatible AI assistant.
Tools
Tool | Description |
| Check server configuration and reachability |
| Library-wide statistics (platforms, ROMs, saves, total size) |
| List platforms with ROM counts and sizes |
| Browse ROMs with filtering and pagination |
| Recently added or updated ROMs |
| Full ROM detail — metadata, saves, user status |
| Search ROMs by name |
| Identify a ROM by file hash (CRC, MD5, or SHA1) |
| Available filter values (genres, regions, languages, tags) |
| List user-curated collections |
| List ROMs in a specific collection |
| List auto-generated smart collections |
| List save files by ROM or platform |
| Browse by status (now playing, backlog, completed, etc.) |
| View notes on a ROM |
| List BIOS/firmware files per platform |
| List registered devices |
| Check running/scheduled task status |
| Trigger a background library rescan |
Setup
Prerequisites
Python 3.10+
A running RomM instance (v4.0+)
A RomM user account with admin role
Install
pip install fastmcp httpxOr clone and install:
git clone https://github.com/lodordev/mcp-romm.git
cd mcp-romm
pip install .Configure
Set environment variables:
Variable | Required | Default | Description |
| No |
| Your RomM instance URL |
| Yes | RomM username | |
| Yes | RomM password | |
| No |
| Default request timeout (seconds) |
| No |
| Timeout for slow endpoints |
| No |
| Verify TLS certificates |
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"
}
}
}
}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?"
Security
Read-only. All 19 tools are read-only. The only mutation is
romm_scan_library, which triggers an idempotent library rescan.No disk writes. Credentials and tokens are held in memory only, never written to disk.
Scoped tokens. OAuth2 tokens request only the scopes needed for read operations.
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 scoped to the minimum permissions needed and automatically refreshed when they expire. If a request gets a 401, the server re-authenticates and retries once.
Note: Your RomM user must have the admin role for all tools to work. The user must also be enabled in the RomM admin panel.
License
MIT
Maintenance
Latest Blog Posts
MCP directory API
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/lodordev/mcp-romm'
If you have feedback or need assistance with the MCP directory API, please join our Discord server