lcu-mcp

一个 MCP 服务器，将正在运行的《英雄联盟》客户端暴露给任何 MCP 主机——包括 LCU REST API、其实时 OnJsonApiEvent 流，以及客户端 UI 自身的 DOM 和 JavaScript 上下文，以九个工具的形式通过 stdio 提供。

让您的助手告诉您当前在哪个队列中，逐事件观察英雄选择过程，检查客户端的 DOM，甚至驱动客户端本身——无需编写一行胶水代码。

目录

• 工作原理

• 环境要求

• 安装

• 注册到 MCP 主机

• 工具

• 配置

• 启用 DOM 访问

• 安全性

• 开发

• 故障排查

• 免责声明

• 许可证

Related MCP server: League of Legends MCP Server

工作原理

两个独立的子系统运行在同一个 Node 进程中：

• LcuClient 读取客户端的 lockfile 以发现端口和密码，然后通过固定 Riot 根 CA 的 HTTPS 进行 REST 通信，并持有一个 OnJsonApiEvent 的 WebSocket 监听，将事件馈入进程内的环形缓冲区。

• CdpClient 连接到客户端的 Chrome DevTools Protocol 端点（由 Pengu Loader 暴露），用于 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 传回。非零的 dropped 表示环形缓冲区已回绕，您的游标之后有那么多事件丢失。带有 truncated: true 的条目其 data 被截断至 4 KB——请使用 lol_get 按条目的 uri 重新获取完整内容。

客户端仅在状态变化时发出事件。 在主页面上闲置时，它可能无限期保持静默；浏览界面或进入大厅会产生突发流量。空轮询通常意味着什么都没发生，而不是监听已损坏——请检查 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

然后重启客户端 UX，让 CEF 拾取该端口：

POST /riotclient/kill-and-restart-ux

这不会影响正在进行的对局。在此之前，两个工具都会以这些确切说明失败，而不是返回裸的 ECONNREFUSED。

安全性

• TLS 验证保持开启。 LCU 的自签名证书会针对 Riot 的根 CA 进行验证，该 CA 已随附于 certs/riotgames.pem。服务器从不设置 rejectUnauthorized: false。

• 密码永远不会离开进程。 它仅用于构建 Authorization 头——没有工具会返回它，没有任何日志记录它，错误文本在到达主机之前也会被清除其中的密码。CDP 目标 URL 也嵌入了密码，因此任何工具返回它们之前都会被脱敏。

• lol_eval 在构造上绕过了写入白名单。 客户端页面可以从其自身源 fetch 任何 LCU 端点，因此被求值的 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