RomM MCP

Servidor MCP para sua plataforma RomM

GitHub

Documentação

🎮 Servidor RomM MCP

Um servidor MCP (Model Context Protocol) para RomM — a plataforma self-hosted de gerenciamento de jogos e ROMs.

Dê ao seu assistente de IA acesso total para navegar, pesquisar e gerenciar sua biblioteca de jogos retrô.

Suporta ambos os transportes:

stdio — uso local via CLI (padrão)
Streamable HTTP — Docker / remoto / múltiplos clientes

Recursos

Navegue por toda a sua biblioteca de ROMs com paginação, filtragem e ordenação
Pesquise jogos por nome em todas as plataformas
Plataformas — liste todas as plataformas com contagens de ROMs e metadados
Coleções — crie, liste, atualize e exclua coleções de jogos
Detalhes de ROM — metadados completos, incluindo gêneros, empresas, classificações, resumos
Firmware — liste arquivos de firmware disponíveis por plataforma
Gerenciamento de saves — navegue por arquivos de save e save states
Notas — operações CRUD de notas anexadas a qualquer ROM
Sistema — verificação de heartbeat, configuração, disparo de varreduras da biblioteca
Capturas de tela — navegue pelas capturas de tela de cada ROM
URLs de download — gere links de download autenticados

Requisitos

Node.js >= 20.0.0
Uma instância RomM em execução (v5.0+)
Uma chave de API do RomM (token rmm_*)

Instalação

Opção 1: npx (sem instalação)

npx romm-mcp

Opção 2: Clonar e compilar

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

Opção 3: Docker

docker compose up -d

Consulte a seção Docker abaixo para obter detalhes.

Segurança

O romm-mcp fornece duas camadas de proteção para evitar modificações não intencionais na sua biblioteca.

Anotações de Ferramentas MCP

Toda ferramenta inclui anotações MCP que informam ao cliente host se uma operação é somente leitura ou destrutiva:

readOnlyHint: true — navegação, pesquisa e listagem (sem efeitos colaterais)
destructiveHint: true — ferramentas que podem excluir dados (coleções, notas)
idempotentHint: true — operações de atualização/criação (seguras para repetição)

Hosts compatíveis com MCP (Claude Desktop, QwenPaw, etc.) usam essas dicas para solicitar automaticamente a confirmação do usuário antes de executar operações destrutivas ou de escrita.

Confirmação de Exclusão

Ferramentas que excluem dados exigem um parâmetro confirm_delete: true explícito. Sem ele, a ferramenta retorna um aviso em vez de executar — isso funciona como uma salvaguarda a nível de aplicação, independentemente do comportamento do host.

Modo Sandbox Somente Leitura

Defina ROMM_READ_ONLY=1 para desabilitar completamente todas as operações de escrita no nível do servidor. Toda ferramenta de mutação (criar, atualizar, excluir, escanear) retornará um erro e se recusará a executar.

Isso é útil quando:

Você expõe o servidor MCP a clientes ou agentes não confiáveis
Você está executando em um contexto "somente leitura" onde a IA deve apenas ler sua biblioteca
Você está testando ou depurando sem risco de mutações acidentais

Configuração

Variáveis de Ambiente

Variável	Obrigatória	Descrição
`ROMM_BASE_URL`	Sim	URL da sua instância RomM (ex.: `http://romm.local:5500`)
`ROMM_API_KEY`	Sim	Chave de API do RomM (gere em RomM → Configurações → Chaves de API)
`MCP_TRANSPORT`	Não	`stdio` (padrão) ou `http` para modo Streamable HTTP
`MCP_PORT`	Não	Porta do servidor HTTP (padrão `3000`, apenas modo HTTP)
`MCP_HOST`	Não	Endereço de bind HTTP (padrão `0.0.0.0`, apenas modo HTTP)
`ROMM_DEBUG`	Não	Defina como `1` para logs de depuração
`ROMM_READ_ONLY`	Não	Defina como `1` para bloquear todas as operações de escrita (modo sandbox)

Obtendo sua Chave de API

Abra a interface web do seu RomM
Vá em Configurações → Chaves de API
Clique em Gerar Chave
Copie o token rmm_...

Uso

Transporte stdio (Local)

Para Claude Desktop, Cursor, CoPaw e outros clientes MCP locais.

Claude Desktop

Adicione em 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

Adicione em agent.json em 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 Streamable HTTP (Remoto / Docker)

Para acesso remoto, implantações Docker ou compartilhamento de um único servidor MCP com vários 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

Em seguida, conecte seu cliente:

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

Docker

Crie um arquivo .env:

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

Depois:

docker compose up -d

Ou use a imagem publicada diretamente:

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 (exemplo 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

Ferramentas

Ferramenta	Descrição
`romm_stats`	Estatísticas da biblioteca — total de plataformas, ROMs, saves, states, capturas de tela, tamanho de arquivo
`romm_list_platforms`	Liste todas as plataformas com contagens de ROMs, categorias e slugs
`romm_browse_roms`	Navegue e filtre ROMs com paginação. Suporta filtros por plataforma, coleção, gênero, empresa, região e ordenação
`romm_get_rom`	Detalhes completos da ROM por ID — metadados, gêneros, empresas, resumo, classificação, link do YouTube
`romm_search_roms`	Pesquise ROMs por nome
`romm_manage_collections`	CRUD de coleções (listar, obter, criar, atualizar, excluir). Também suporta coleções inteligentes e virtuais
`romm_get_collection_roms`	Liste todas as ROMs em uma coleção específica
`romm_list_firmware`	Liste arquivos de firmware disponíveis por plataforma
`romm_download_rom`	Gere uma URL de download autenticada para uma ROM
`romm_update_rom`	Atualize metadados da ROM — nome de exibição, notas, status de favorito
`romm_rom_notes`	Gerencie notas anexadas a uma ROM (listar, adicionar, atualizar, excluir)
`romm_manage_saves`	Liste arquivos de save, opcionalmente filtrados por ROM
`romm_manage_states`	Liste arquivos de save state, opcionalmente filtrados por ROM
`romm_system`	Operações de sistema — heartbeat, configuração, disparo de varredura da biblioteca, atualização de metadados
`romm_screenshots`	Liste capturas de tela, opcionalmente filtradas por ROM

Exemplos de Interação

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

Desenvolvimento

# 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

Arquitetura

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

O cliente de API é um wrapper fino sobre a API REST do RomM (OpenAPI 3.1.0). Ele usa fetch nativo — nenhuma biblioteca HTTP externa é necessária.

No modo HTTP, o servidor usa Hono com o WebStandardStreamableHTTPServerTransport sem estado — um novo servidor MCP é criado por requisição, tornando-o seguro para Docker e cenários com múltiplos clientes.

Compatibilidade

RomM v5.0+ (testado com v5.0.0-beta.1)
Node.js >= 20 (usa fetch nativo)
Qualquer cliente compatível com MCP (Claude Desktop, CoPaw, Cursor, Windsurf, etc.)
Especificação MCP Streamable HTTP (2025-03-26)

Mudanças no RomM 5.0

Mudança de Quebra: O RomM 5.0 removeu o endpoint de API POST /api/tasks/run. As varreduras da biblioteca e as atualizações de metadados agora são gerenciadas por meio de workers RQ e não podem ser acionadas via API.

As seguintes ferramentas agora retornam mensagens de orientação:

romm_system → ação scan: Retorna uma mensagem para usar a interface web do RomM (Configurações → Tarefas)
romm_system → ação metadata_scan: Retorna uma mensagem para usar a interface web do RomM (Configurações → Tarefas)

Todas as outras ferramentas continuam funcionando como antes.

Licença

MIT