RomM MCP
About
MCP Server for your RomM platform
Details
- Author
- rodrigosiviero
- Categories
- Other, Database, File Management
Jump to
Setup
Install RomM MCP in your MCP client (Claude Desktop, Cursor, Windsurf, and others).
Repository: https://github.com/rodrigosiviero/romm-mcp
Follow the installation instructions in the repository README, then restart your MCP client.
Give your AI assistant full access to browse, search, and manage your retro game library.
- stdio— local CLI usage (default)
- Streamable HTTP— Docker / remote / multi-client
- Browseyour full ROM library with pagination, filtering, and sorting
- Searchgames by name across all platforms
- Platforms— list all platforms with ROM counts and metadata
- Collections— create, list, update, and delete game collections
- ROM details— full metadata including genres, companies, ratings, summaries
- Firmware— list available firmware files per platform
- Save management— browse save files and save states
- Notes— CRUD notes attached to any ROM
- System— heartbeat check, config, trigger library scans
- Screenshots— browse screenshots per ROM
- Download URLs— generate authenticated download links
- Node.js >= 20.0.0
- A runningRomMinstance (v5.0+)
- A RomM API key (rmm_*token)
git clone https://github.com/rodrigosiviero/romm-mcp.git cd romm-mcp npm install npm run build
romm-mcp provides two layers of protection to prevent unintended modifications to your library.
Every tool includesMCP annotationsthat inform the host client whether an operation is read-only or destructive:
- readOnlyHint: true— browsing, searching, and listing (no side effects)
- destructiveHint: true— tools that can delete data (collections, notes)
- idempotentHint: true— update/create operations (safe to retry)
MCP-compliant hosts (Claude Desktop, QwenPaw, etc.) use these hints to automatically prompt the user before executing destructive or write operations.
Tools that delete data require an explicitconfirm_delete: trueparameter. Without it, the tool returns a warning instead of executing — this acts as an application-level safeguard regardless of the host's behavior.
SetROMM_READ_ONLY=1to completely disable all write operations at the server level. Every mutating tool (create, update, delete, scan) will return an error and refuse to execute.
- Exposing the MCP server to untrusted clients or agents
- Running in a "browse-only" context where the AI should only read your library
- Testing or debugging without risk of accidental mutations
- Open your RomM web UI
- Go toSettings→API Keys
- ClickGenerate Key
- Copy thermm_...token
For Claude Desktop, Cursor, CoPaw, and other local MCP clients.
{ "mcpServers": { "romm": { "command": "npx", "args": ["-y", "romm-mcp"], "env": { "ROMM_BASE_URL": "http://your-romm-instance:5500", "ROMM_API_KEY": "rmm_your_api_key_here" } } } }
{ "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": "rmm_your_api_key_here" } } }
Streamable HTTP Transport (Remote / Docker)
For remote access, Docker deployments, or sharing one MCP server with multiple clients.
MCP_TRANSPORT=http MCP_PORT=3000 \ ROMM_BASE_URL=http://your-romm-instance:5500 \ ROMM_API_KEY=rmm_your_api_key_here \ npx romm-mcp
{ "mcpServers": { "romm": { "type": "streamable-http", "url": "http://localhost:3000/mcp" } } }
ROMM_BASE_URL=http://host.docker.internal:5500 ROMM_API_KEY=rmm_your_api_key_here
docker run -d \ --name romm-mcp \ -p 3000:3000 \ -e ROMM_BASE_URL=http://host.docker.internal:5500 \ -e ROMM_API_KEY=rmm_your_api_key_here \ ghcr.io/rodrigosiviero/romm-mcp:main
services: romm-mcp: image: ghcr.io/rodrigosiviero/romm-mcp:main ports: - "3000:3000" environment: - MCP_TRANSPORT=http - MCP_PORT=3000 - ROMM_BASE_URL=http://host.docker.internal:5500 - ROMM_API_KEY=rmm_your_api_key_here restart: unless-stopped healthcheck: test: ["CMD", "wget", "-O-", "http://127.0.0.1:3000/health"] interval: 30s timeout: 5s retries: 3
You: How many games do I have? 🤖: 📊 RomM Library Stats Platforms: 20 ROMs: 1,362 Saves: 1 States: 0 Screenshots: 0 Total Size: 197.4 GB
You: Find Mario games in my library 🤖: 🔍 Search: "mario" (5 results) • [4227] Mario Kart 8 Deluxe (Nintendo Switch) • [4108] Mario Andretti Racing (Sega Mega Drive/Genesis) • [921] Super Mario RPG (Nintendo Switch) • [933] Paper Mario (Wii) • [4109] Mario Lemieux Hockey (Sega Mega Drive/Genesis)
You: Tell me about Super Mario RPG 🤖: 🎮 Super Mario RPG Platform: Nintendo Switch File: Super Mario RPG [0100BC0018138000][v0].nsp (6.4 GB) 📝 Summary: Mario, Bowser, and Peach partner up to repair the wish-granting Star Road in this approachable role-playing adventure. 🏷️ Genres: Adventure, Role-playing (RPG) 🏢 Companies: ArtePiazza, Flame Hearts, Nintendo 🔗 Franchises: Mario ⭐ Rating: 80.51 📅 Release: 11/17/2023
# Install dependencies npm install # Build npm run build # Run with stdio (default) ROMM_BASE_URL=http://localhost:5500 ROMM_API_KEY=rmm_xxx node dist/index.js # Run with HTTP MCP_TRANSPORT=http ROMM_BASE_URL=http://localhost:5500 ROMM_API_KEY=rmm_xxx node dist/index.js
src/ ├── client.ts # RomM REST API client (fetch-based, zero deps) ├── server.ts # MCP server with all tools (shared between transports) └── index.ts # Entry point — auto-detects stdio vs HTTP
The API client is a thin wrapper over theRomM REST API(OpenAPI 3.1.0). It uses nativefetch— no external HTTP library needed.
In HTTP mode, the server usesHonowith the statelessWebStandardStreamableHTTPServerTransport— a fresh MCP server is created per request, making it safe for Docker and multi-client scenarios.
- RomM v5.0+ (tested with v5.0.0-beta.1)
- Node.js >= 20 (uses nativefetch)
- Any MCP-compatible client (Claude Desktop, CoPaw, Cursor, Windsurf, etc.)
- MCP Streamable HTTP spec (2025-03-26)
Breaking Change: RomM 5.0 removed thePOST /api/tasks/runAPI endpoint. Library scans and metadata updates are now managed through RQ workers and cannot be triggered via API.
The following tools now return guidance messages:
- romm_system→scanaction: Returns a message to use the RomM web UI (Settings → Tasks)
- romm_system→metadata_scanaction: Returns a message to use the RomM web UI (Settings → Tasks)
All other tools continue to work as before.
A server for managing Dungeons & Dragons campaigns, storing all data in local JSON files.
Structured iGaming reference data — slot specs, RTP variants, providers, regulators, news and jobs.
Access Dungeons & Dragons 5th Edition content, including spells, classes, and monsters, via the Open5e API.
Manage multiple Fireproof JSON document databases with cloud sync capabilities.
Access the IGDB (Internet Game Database) API through Model Context Protocol (MCP)
Provides real-time, structured access to League of Legends game data, including champions, items, abilities, game mechanics, and patch information.
Process SGF (Smart Game Format) files to extract game information and generate visual board diagrams.
A knowledge graph server for AI models, focusing on text-based RPGs and interactive storytelling.
Magic: The Gathering (MTG) servers for deck management and card search using the MCP protocol.
An MCP server for intelligent access to your local music collection, featuring metadata management, band discovery, and advanced querying.
Sign in to leave a review
Use Google, GitHub, or an email account so ratings stay tied to real people.
No reviews posted yet.
