lcu-mcp

Un servidor MCP que expone un cliente de League of Legends en ejecución a cualquier host MCP — la API REST de LCU, su flujo en vivo OnJsonApiEvent, y el propio DOM y contexto JavaScript de la interfaz del cliente, como nueve herramientas sobre stdio.

Pregúntale a tu asistente en qué cola estás, observa cómo se desarrolla la selección de campeones evento por evento, inspecciona el DOM del cliente o controla el propio cliente — sin escribir una línea de código de integración.

Contenido

• Cómo funciona

• Requisitos

• Instalación

• Registro con un host MCP

• Herramientas

• Configuración

• Habilitar el acceso al DOM

• Seguridad

• Desarrollo

• Solución de problemas

• Aviso legal

• Licencia

Related MCP server: League of Legends MCP Server

Cómo funciona

Dos subsistemas independientes se ejecutan dentro de un mismo proceso de Node:

• LcuClient lee el archivo lockfile del cliente para descubrir el puerto y la contraseña, luego habla REST sobre HTTPS con la CA raíz de Riot fijada, y mantiene un grifo WebSocket en OnJsonApiEvent que alimenta un búfer circular en el proceso.

• CdpClient se conecta al endpoint de Chrome DevTools Protocol del cliente (expuesto por Pengu Loader) para consultas del DOM y evaluación de JavaScript.

Ambos se conectan de forma perezosa y sobreviven a los reinicios del cliente — el puerto del lockfile cambia en cada lanzamiento, por lo que se observa el directorio en lugar del archivo. Los eventos se sondean en lugar de enviarse, porque MCP no tiene push de servidor a cliente.

La justificación del diseño y los detalles del protocolo verificados en vivo están en docs/design.md.

Requisitos

Solo Windows en la práctica: la ruta predeterminada del lockfile y la integración con Pengu son específicas de Windows.

Instalación

git clone https://github.com/Triggered0/lcu-mcp.git
cd lcu-mcp
npm install

Las dependencias de ejecución son exactamente tres: @modelcontextprotocol/sdk, zod y ws.

Registro con un host MCP

Claude Code

claude mcp add lcu --scope user -- node C:\path\to\lcu-mcp\src\index.js

Cualquier host que lea .mcp.json

{
  "mcpServers": {
    "lcu": {
      "command": "node",
      "args": ["C:\\path\\to\\lcu-mcp\\src\\index.js"],
      "env": { "LCU_MCP_CONFIG": "C:\\path\\to\\lcu-mcp\\config\\allowlist.json" }
    }
  }
}

LCU_MCP_CONFIG es opcional; sin él, el servidor busca config/allowlist.json relativo a su directorio de trabajo, y recurre a los valores predeterminados integrados si ese archivo no existe.

Herramientas

lol_status primero. Cuando cualquier otra cosa falla, te dice qué mitad está caída — un cliente cerrado no se parece en nada a una instalación de Pengu faltante.

Los eventos se sondean. lol_events_poll devuelve un cursor; pásalo de vuelta como since la próxima vez. Un dropped distinto de cero significa que el búfer circular se envolvió y que se perdieron tantos eventos después de tu cursor. Las entradas con truncated: true tuvieron su data recortada a 4 KB — vuelve a obtener el cuerpo completo con lol_get en el uri de la entrada.

El cliente solo emite cuando el estado cambia. Sentado inactivo en la pantalla de inicio puede permanecer en silencio indefinidamente; navegar por la interfaz o entrar en una sala produce ráfagas. Una encuesta vacía generalmente significa que no pasó nada, no que el grifo esté roto — comprueba running y lol_status para distinguir los dos casos.

Los filtros son prefijos de URI aplicados en la ingesta. El flujo sin filtrar llena el búfer rápidamente, así que pasa algo como ["/lol-champ-select/", "/lol-gameflow/"] a menos que realmente quieras todo.

Configuración

config/allowlist.json:

{
  "allowEval": true,
  "cdpPort": 8888,
  "eventBufferSize": 1000,
  "writeAllowlist": [
    "POST /lol-matchmaking/v1/ready-check/accept",
    "PATCH /lol-champ-select/v1/session/actions/*"
  ]
}

Reglas de coincidencia de la lista blanca:

• Una entrada es METHOD path. El método se compara sin distinguir mayúsculas de minúsculas, la ruta distinguiendo mayúsculas de minúsculas.

• GET y HEAD siempre están permitidos y no necesitan entrada.

• * solo tiene significado como segmento de ruta final: /a/b/* coincide con /a/b/c pero no con /a/b/c/d ni con /a/b. En cualquier otro lugar es un carácter literal.

• Una llamada rechazada devuelve la línea de configuración exacta que la permitiría, y la solicitud nunca se envía.

Habilitar el acceso al DOM

lol_dom_query y lol_eval necesitan el puerto de depuración remota CEF del cliente, que la compilación de Riot solo abre a través de Pengu Loader — una bandera --remote-debugging-port añadida externamente se ignora.

La configuración de Pengu es texto plano clave=valor, un par por línea — no JSON, no INI. En C:\Program Files\Pengu Loader\config, establece:

RemoteDebuggingPort=8888

Luego reinicia la interfaz del cliente para que CEF tome el puerto:

POST /riotclient/kill-and-restart-ux

Esto deja un juego en vivo intacto. Hasta que suceda, ambas herramientas fallan con estas instrucciones exactas en lugar de un simple ECONNREFUSED.

Seguridad

• La verificación TLS permanece activada. El certificado autofirmado de LCU se valida contra la CA raíz de Riot, incluida en certs/riotgames.pem. El servidor nunca establece rejectUnauthorized: false.

• La contraseña nunca sale del proceso. Se mantiene solo para construir el encabezado Authorization — ninguna herramienta la devuelve, nada la registra, y el texto de error se limpia de ella antes de que llegue al host. Las URL de destino de CDP también la incrustan, por lo que se redactan antes de que cualquier herramienta las devuelva.

• lol_eval elude la lista blanca de escritura por construcción. La página del cliente puede hacer fetch a cualquier endpoint de LCU desde su propio origen, por lo que el JavaScript evaluado puede hacer cualquier cosa que el cliente pueda. Esto se acepta, no se corrige: está controlado por la bandera allowEval, cuyo estado informa lol_status.

Trata la lista blanca de escritura como una protección contra errores, no como un límite de seguridad — mientras allowEval sea true, se puede eludir. Establece allowEval en false para un límite real. lol_dom_query sigue funcionando, porque inyecta el selector como dato en lugar de como código.

Desarrollo

npm test        # unit tests via node:test — no League client needed
npm run smoke   # live end-to-end check against a running client
npm start       # run the server on stdio

npm run smoke imprime una línea por etapa y sale con 1 si alguna etapa falla. Nunca se ejecuta en CI. La etapa de eventos espera la entrega real e informa tres resultados: PASS cuando llegaron eventos, SKIP cuando el grifo se conectó pero un cliente inactivo no envió nada, y FAIL cuando el grifo no pudo conectarse.

src/
  index.js          # stdio transport and tool registration
  config.js         # config loading and validation
  allowlist.js      # pure write-allowlist matching
  redact.js         # strip passwords from URLs and strings
  lcu/
    lockfile.js     # parse, read, and watch the lockfile
    client.js       # REST with the pinned CA
    buffer.js       # ring buffer with cursor and drop accounting
    ingest.js       # pure ingest policy: prefix filters, truncation
    events.js       # WebSocket tap with backoff reconnect
  cdp/
    discover.js     # probe the debugging port, pick and redact the target
    client.js       # attach, evaluate, DOM query
  tools/            # one module per tool group
tests/              # one test file per source module

Solución de problemas

Aviso legal

lcu-mcp no está respaldado por Riot Games y no refleja las opiniones de Riot Games ni de nadie involucrado oficialmente en la producción o gestión de las propiedades de Riot Games. Riot Games y todas las propiedades asociadas son marcas comerciales o marcas registradas de Riot Games, Inc.

Este proyecto utiliza la API local del propio cliente. Eres responsable de cómo la usas; automatizar el juego puede violar los Términos de Servicio de Riot.

Licencia

MIT © Triggered