lcu-mcp

실행 중인 League of Legends 클라이언트를 모든 MCP 호스트에 노출하는 MCP 서버입니다 — LCU REST API, 실시간 OnJsonApiEvent 스트림, 클라이언트 UI의 자체 DOM 및 JavaScript 컨텍스트를 stdio를 통해 9개의 도구로 제공합니다.

어시스턴트에게 현재 어떤 큐에 있는지 물어보고, 챔피언 선택이 이벤트별로 전개되는 것을 지켜보고, 클라이언트의 DOM을 검사하거나, 클라이언트 자체를 구동하세요 — 글루 코드 한 줄 없이.

목차

• 작동 방식

• 요구 사항

• 설치

• MCP 호스트에 등록

• 도구

• 구성

• DOM 접근 활성화

• 보안

• 개발

• 문제 해결

• 면책 조항

• 라이선스

Related MCP server: League of Legends MCP Server

작동 방식

하나의 Node 프로세스 안에서 두 개의 독립적인 하위 시스템이 실행됩니다:

• LcuClient 는 클라이언트의 lockfile을 읽어 포트와 비밀번호를 찾은 다음, Riot의 루트 CA를 고정하여 HTTPS로 REST 통신을 하고, OnJsonApiEvent에 대한 WebSocket 탭을 유지하여 프로세스 내 링 버퍼에 공급합니다.

• CdpClient 는 (Pengu Loader가 노출하는) 클라이언트의 Chrome DevTools Protocol 엔드포인트에 연결하여 DOM 쿼리와 JavaScript 평가를 수행합니다.

둘 다 지연 연결 방식이며 클라이언트 재시작에도 살아남습니다 — lockfile 포트는 실행할 때마다 바뀌므로 파일이 아니라 디렉터리를 감시합니다. 이벤트는 푸시가 아닌 폴링 방식입니다. MCP에는 서버에서 클라이언트로의 푸시가 없기 때문입니다.

설계 근거와 실시간 검증된 프로토콜 세부 사항은 docs/design.md에 있습니다.

요구 사항

실제로는 Windows 전용입니다: 기본 lockfile 경로와 Pengu 통합이 Windows 전용이기 때문입니다.

설치

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

런타임 의존성은 정확히 세 가지입니다: @modelcontextprotocol/sdk, zod, ws.

MCP 호스트에 등록

Claude Code

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

.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는 선택 사항입니다. 없으면 서버는 작업 디렉터리 기준으로 config/allowlist.json을 찾고, 해당 파일이 없으면 내장 기본값으로 대체합니다.

도구

먼저 lol_status를 확인하세요. 다른 것이 실패하면 어느 쪽이 다운되었는지 알려줍니다 — 닫힌 클라이언트는 Pengu 설치 누락과 전혀 다르게 보입니다.

이벤트는 폴링됩니다. lol_events_poll은 cursor를 반환합니다. 다음에 since로 다시 전달하세요. 0이 아닌 dropped는 링 버퍼가 감싸져 커서 이후 그만큼의 이벤트가 손실되었음을 의미합니다. truncated: true 항목은 data가 4KB에서 잘렸다는 뜻입니다 — 항목의 uri로 lol_get을 사용하여 전체 본문을 다시 가져오세요.

클라이언트는 상태가 변경될 때만 이벤트를 내보냅니다. 홈 화면에서 유휴 상태로 있으면 무기한 조용할 수 있습니다. UI를 탐색하거나 로비에 들어가면 버스트가 발생합니다. 빈 폴링은 일반적으로 아무 일도 일어나지 않았다는 뜻이지 탭이 고장났다는 뜻이 아닙니다 — running과 lol_status를 확인하여 둘을 구분하세요.

필터는 수집 시 적용되는 URI 접두사입니다. 필터링되지 않은 파이어호스는 버퍼를 빠르게 채우므로, 정말 모든 것을 원하지 않는 한 ["/lol-champ-select/", "/lol-gameflow/"] 같은 것을 전달하세요.

구성

config/allowlist.json:

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

허용 목록 일치 규칙:

• 항목은 METHOD path 형식입니다. 메서드는 대소문자를 구분하지 않고 비교되며, 경로는 대소문자를 구분합니다.

• GET 및 HEAD는 항상 허용되며 항목이 필요 없습니다.

• *는 경로의 마지막 세그먼트로만 의미가 있습니다: /a/b/*는 /a/b/c와 일치하지만 /a/b/c/d나 /a/b와는 일치하지 않습니다. 다른 위치에서는 리터럴 문자입니다.

• 거부된 호출은 이를 허용할 정확한 구성 줄을 반환하며, 요청은 전송되지 않습니다.

DOM 접근 활성화

lol_dom_query 및 lol_eval은 클라이언트의 CEF 원격 디버깅 포트가 필요합니다. Riot 빌드는 Pengu Loader를 통해서만 이 포트를 엽니다 — 외부에서 추가된 --remote-debugging-port 플래그는 무시됩니다.

Pengu의 구성은 일반 key=value 텍스트로, 줄마다 한 쌍입니다 — JSON도 INI도 아닙니다. C:\Program Files\Pengu Loader\config에서 다음을 설정하세요:

RemoteDebuggingPort=8888

그런 다음 CEF가 포트를 인식하도록 클라이언트 UX를 다시 시작하세요:

POST /riotclient/kill-and-restart-ux

이렇게 해도 진행 중인 게임에는 영향이 없습니다. 그 전까지 두 도구는 단순한 ECONNREFUSED 대신 이 정확한 지침과 함께 실패합니다.

보안

• TLS 검증은 유지됩니다. LCU의 자체 서명 인증서는 certs/riotgames.pem에 포함된 Riot의 루트 CA에 대해 검증됩니다. 서버는 절대 rejectUnauthorized: false를 설정하지 않습니다.

• 비밀번호는 프로세스를 떠나지 않습니다. Authorization 헤더를 만드는 데만 사용됩니다 — 어떤 도구도 반환하지 않으며, 로그에도 남지 않고, 호스트에 도달하기 전에 오류 텍스트에서 제거됩니다. CDP 대상 URL에도 비밀번호가 포함되므로 어떤 도구가 반환하기 전에 삭제됩니다.

• lol_eval은 구조적으로 쓰기 허용 목록을 우회합니다. 클라이언트 페이지는 자체 출처에서 모든 LCU 엔드포인트를 fetch할 수 있으므로, 평가된 JavaScript는 클라이언트가 할 수 있는 모든 것을 할 수 있습니다. 이는 수정되지 않고 수용됩니다: allowEval 플래그로 제한되며, 그 상태는 lol_status가 보고합니다.

쓰기 허용 목록을 보안 경계가 아닌 실수 방지용 가드레일로 취급하세요 — allowEval이 true인 동안에는 우회할 수 있습니다. 실제 경계를 원하면 allowEval을 false로 설정하세요. lol_dom_query는 계속 작동합니다. 선택자를 코드가 아닌 데이터로 주입하기 때문입니다.

개발

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는 각 단계마다 한 줄을 출력하고 어떤 단계라도 실패하면 1로 종료합니다. CI에서는 실행되지 않습니다. 이벤트 단계는 실제 전달을 기다리며 세 가지 결과를 보고합니다: 이벤트가 도착하면 PASS, 탭이 연결되었지만 유휴 클라이언트가 아무것도 보내지 않으면 SKIP, 탭이 연결되지 않으면 FAIL.

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

문제 해결

면책 조항

lcu-mcp는 Riot Games의 보증을 받지 않으며 Riot Games 또는 Riot Games 자산의 제작 및 관리에 공식적으로 참여하는 사람의 견해나 의견을 반영하지 않습니다. Riot Games 및 모든 관련 자산은 Riot Games, Inc.의 상표 또는 등록 상표입니다.

이 프로젝트는 클라이언트의 자체 로컬 API를 사용합니다. 사용 방법에 대한 책임은 사용자에게 있습니다. 게임플레이 자동화는 Riot의 서비스 약관을 위반할 수 있습니다.

라이선스

MIT © Triggered