RomM MCP

Servidor MCP para tu plataforma RomM

GitHub

Documentación

🎮 Servidor RomM MCP

Un servidor MCP (Model Context Protocol) para RomM — la plataforma autogestionada de juegos y gestión de ROMs.

Dale a tu asistente de IA acceso completo para explorar, buscar y gestionar tu biblioteca de juegos retro.

Soporta ambos transportes:

stdio — uso local por CLI (predeterminado)
HTTP Streamable — Docker / remoto / multi-cliente

Características

Explora tu biblioteca completa de ROMs con paginación, filtros y ordenamiento
Busca juegos por nombre en todas las plataformas
Plataformas — lista todas las plataformas con conteos de ROMs y metadatos
Colecciones — crea, lista, actualiza y elimina colecciones de juegos
Detalles de ROM — metadatos completos incluyendo géneros, compañías, calificaciones, resúmenes
Firmware — lista archivos de firmware disponibles por plataforma
Gestión de guardados — explora archivos de guardado y estados de guardado
Notas — operaciones CRUD de notas adjuntas a cualquier ROM
Sistema — verificación de heartbeat, configuración, activación de escaneos de biblioteca
Capturas de pantalla — explora capturas por ROM
URLs de descarga — genera enlaces de descarga autenticados

Requisitos

Node.js >= 20.0.0
Una instancia de RomM en ejecución (v5.0+)
Una clave API de RomM (token rmm_*)

Instalación

Opción 1: npx (sin instalación necesaria)

npx romm-mcp

Opción 2: Clonar y compilar

git clone https://github.com/rodrigosiviero/romm-mcp.git
cd romm-mcp
npm install
npm run build

Opción 3: Docker

docker compose up -d

Consulta la sección Docker a continuación para más detalles.

Seguridad

romm-mcp proporciona dos capas de protección para prevenir modificaciones no deseadas en tu biblioteca.

Anotaciones de herramientas MCP

Cada herramienta incluye anotaciones MCP que informan al cliente anfitrión si una operación es de solo lectura o destructiva:

readOnlyHint: true — explorar, buscar y listar (sin efectos secundarios)
destructiveHint: true — herramientas que pueden eliminar datos (colecciones, notas)
idempotentHint: true — operaciones de actualización/creación (seguras de reintentar)

Los anfitriones compatibles con MCP (Claude Desktop, QwenPaw, etc.) usan estas indicaciones para solicitar automáticamente al usuario antes de ejecutar operaciones destructivas o de escritura.

Confirmar eliminaciones

Las herramientas que eliminan datos requieren un parámetro explícito confirm_delete: true. Sin él, la herramienta devuelve una advertencia en lugar de ejecutarse — esto actúa como una salvaguarda a nivel de aplicación independientemente del comportamiento del anfitrión.

Modo sandbox de solo lectura

Establece ROMM_READ_ONLY=1 para deshabilitar completamente todas las operaciones de escritura a nivel del servidor. Cada herramienta de mutación (crear, actualizar, eliminar, escanear) devolverá un error y se negará a ejecutarse.

Esto es útil cuando:

Expones el servidor MCP a clientes o agentes no confiables
Ejecutas en un contexto de "solo exploración" donde la IA solo debe leer tu biblioteca
Pruebas o depuras sin riesgo de mutaciones accidentales

Configuración

Variables de entorno

Variable	Requerida	Descripción
`ROMM_BASE_URL`	Sí	URL de tu instancia de RomM (ej. `http://romm.local:5500`)
`ROMM_API_KEY`	Sí	Clave API de RomM (generar en RomM → Configuración → Claves API)
`MCP_TRANSPORT`	No	`stdio` (predeterminado) o `http` para modo HTTP Streamable
`MCP_PORT`	No	Puerto del servidor HTTP (predeterminado `3000`, solo modo HTTP)
`MCP_HOST`	No	Dirección de enlace HTTP (predeterminado `0.0.0.0`, solo modo HTTP)
`ROMM_DEBUG`	No	Establece a `1` para registros de depuración
`ROMM_READ_ONLY`	No	Establece a `1` para bloquear todas las operaciones de escritura (modo sandbox)

Cómo obtener tu clave API

Abre la interfaz web de RomM
Ve a Configuración → Claves API
Haz clic en Generar clave
Copia el token rmm_...

Uso

Transporte stdio (Local)

Para Claude Desktop, Cursor, CoPaw y otros clientes MCP locales.

Claude Desktop

Agrega a claude_desktop_config.json:

{
  "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"
      }
    }
  }
}

CoPaw / OpenClaw

Agrega a agent.json bajo mcp.clients:

{
  "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"
    }
  }
}

Transporte HTTP Streamable (Remoto / Docker)

Para acceso remoto, implementaciones Docker o compartir un servidor MCP con múltiples clientes.

HTTP local

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

Luego conecta tu cliente:

{
  "mcpServers": {
    "romm": {
      "type": "streamable-http",
      "url": "http://localhost:3000/mcp"
    }
  }
}

Docker

Crea un archivo .env:

ROMM_BASE_URL=http://host.docker.internal:5500
ROMM_API_KEY=rmm_your_api_key_here

Luego:

docker compose up -d

O usa la imagen publicada directamente:

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

Docker Compose (ejemplo completo)

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

Herramientas

Herramienta	Descripción
`romm_stats`	Estadísticas de la biblioteca — total de plataformas, ROMs, guardados, estados, capturas, tamaño de archivos
`romm_list_platforms`	Lista todas las plataformas con conteos de ROMs, categorías y slugs
`romm_browse_roms`	Explora y filtra ROMs con paginación. Soporta filtros de plataforma, colección, género, compañía, región y ordenamiento
`romm_get_rom`	Detalles completos de ROM por ID — metadatos, géneros, compañías, resumen, calificación, enlace de YouTube
`romm_search_roms`	Busca ROMs por nombre
`romm_manage_collections`	Operaciones CRUD de colecciones (listar, obtener, crear, actualizar, eliminar). También soporta colecciones inteligentes y virtuales
`romm_get_collection_roms`	Lista todos los ROMs en una colección específica
`romm_list_firmware`	Lista archivos de firmware disponibles por plataforma
`romm_download_rom`	Genera una URL de descarga autenticada para un ROM
`romm_update_rom`	Actualiza metadatos de ROM — nombre mostrado, notas, estado de favorito
`romm_rom_notes`	Gestiona notas adjuntas a un ROM (listar, agregar, actualizar, eliminar)
`romm_manage_saves`	Lista archivos de guardado, opcionalmente filtrados por ROM
`romm_manage_states`	Lista archivos de estado de guardado, opcionalmente filtrados por ROM
`romm_system`	Operaciones del sistema — heartbeat, configuración, activación de escaneo de biblioteca, actualización de metadatos
`romm_screenshots`	Lista capturas de pantalla, opcionalmente filtradas por ROM

Ejemplos de interacción

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

Desarrollo

# 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

Arquitectura

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

El cliente API es un envoltorio delgado sobre la API REST de RomM (OpenAPI 3.1.0). Usa fetch nativo — no se necesita biblioteca HTTP externa.

En modo HTTP, el servidor usa Hono con el WebStandardStreamableHTTPServerTransport sin estado — se crea un servidor MCP nuevo por solicitud, lo que lo hace seguro para Docker y escenarios multi-cliente.

Compatibilidad

RomM v5.0+ (probado con v5.0.0-beta.1)
Node.js >= 20 (usa fetch nativo)
Cualquier cliente compatible con MCP (Claude Desktop, CoPaw, Cursor, Windsurf, etc.)
Especificación MCP Streamable HTTP (2025-03-26)

Cambios en RomM 5.0

Cambio importante: RomM 5.0 eliminó el endpoint de API POST /api/tasks/run. Los escaneos de biblioteca y las actualizaciones de metadatos ahora se gestionan a través de trabajadores RQ y no se pueden activar mediante API.

Las siguientes herramientas ahora devuelven mensajes de orientación:

romm_system → acción scan: Devuelve un mensaje para usar la interfaz web de RomM (Configuración → Tareas)
romm_system → acción metadata_scan: Devuelve un mensaje para usar la interfaz web de RomM (Configuración → Tareas)

Todas las demás herramientas continúan funcionando como antes.

Licencia

MIT