winchrome

从 WSL 里直接操控 Windows 端 Chrome。 把 chrome-devtools-mcp 放到 Windows 侧运行， 让 WSL 中的 AI agent（DeepSeek Harness、Claude Code、Cursor…）能导航、点击、填表、执行 JS、 读无障碍树、截图——就像浏览器长在 WSL 里一样。

EN: Drive Windows-side Chrome from WSL. The MCP server runs on Windows (via WSL interop) so it can reach Chrome's loopback-only DevTools endpoint, which WSL cannot. All paths are auto-detected, so there is no config to fill in. Built for chrome-devtools-mcp.

为什么需要它

三个限制叠在一起，导致「WSL 直接连 Windows 的 Chrome 调试端口」走不通：

绕法只有一条：把 MCP 服务器放到 Windows 侧跑（用 Windows 自带的 node.exe，通过 WSL interop 启动），它到 Chrome 就是本机连接。不需要管理员权限、不需要 netsh portproxy、 不需要把 WSL 改成 mirrored 网络模式。

WSL: agent / CLI
      │  stdio (JSON-RPC over WSL interop)
      ▼
Windows: node.exe + chrome-devtools-mcp ──本机 ws──► 浏览器 127.0.0.1:9222

Related MCP server: wsl-chrome-mcp-bridge

安装

前置条件

• Windows 10/11，装有 Chrome（或 Edge）

• WSL2 + 任一发行版，且 WSL interop 可用（默认开启，在 WSL 里能跑 cmd.exe 就说明可用）

• Windows 侧装有 Node.js（用来跑 chrome-devtools-mcp）：https://nodejs.org

• WSL 侧装有 Node.js ≥ 18

第 1 步：在 Windows 侧安装 chrome-devtools-mcp

在 Windows 的 PowerShell / cmd 里执行：

npm install --prefix "%USERPROFILE%\.winchrome" chrome-devtools-mcp

装到别处也行，用环境变量 WIN_MCP 指过去即可（见下方「环境变量」）。 本工具会自动在这几个位置找它：

%USERPROFILE%\.winchrome\node_modules\chrome-devtools-mcp\...
%USERPROFILE%\.dsh-mcp\node_modules\chrome-devtools-mcp\...
%APPDATA%\npm\node_modules\chrome-devtools-mcp\...   （npm i -g 的全局安装）

第 2 步：在 WSL 侧获取本项目

git clone https://github.com/ZinChl/winchrome.git ~/extensions/winchrome
cd ~/extensions/winchrome

零依赖，不需要 npm install——只用 Node 内置模块。

第 3 步：确认探测结果

node winchrome.mjs status

正常会打印自动探测到的 Windows 用户名、浏览器路径、调试 profile 与端口状态。某项不对就用 环境变量覆盖。

第 4 步：启动调试用浏览器并验证

node winchrome.mjs start     # 用独立 profile 启动浏览器（不影响你日常那个）
node winchrome.mjs pages     # 应列出当前标签页

到这里 CLI 已经可用。想让浏览器由你自己手动开关，见下方「日常使用」。

第 5 步（可选）：接入 MCP 客户端

以 DeepSeek Harness 的 ~/.dsh/profiles/web/cordis.patch.yml 为例：

- insert:
    - id: mcp-winchrome
      name: '@deepseek-ai/dsh-mcp-client'
      config:
        transport: stdio
        serverName: winchrome
        command: /home/<你>/.nvm/versions/node/v22.23.1/bin/node   # WSL 里的 node 绝对路径
        args:
          - /home/<你>/extensions/winchrome/mcp-entry.mjs
        env:
          WIN_CHROME_MODE: debug          # 专用调试 profile，零授权弹窗
          WIN_CHROME_AUTOSTART: '0'       # 不自动拉起浏览器，交给开关脚本
          WIN_MCP_EXTRA: '--screenshotFormat jpeg --screenshotQuality 70'
        toolCallTimeoutMs: 120000

其它 MCP 客户端（Claude Desktop / Cursor / Cline…）用同样的 command + args 即可。 工具名会以 mcp__winchrome__ 开头，例如 mcp__winchrome__navigate_page。

日常使用

手动开关浏览器（推荐）

scripts/chrome-debug.ps1 提供 start / stop / status / toggle 四个动作， 同目录的 scripts/chrome-debug.cmd 双击即切换启停。想放桌面就把这两个文件一起复制过去 （保持在同一目录）：

powershell -NoProfile -ExecutionPolicy Bypass -File chrome-debug.ps1 toggle

关掉浏览器不影响 agent：MCP 服务器仍常驻，浏览器一回来，下一次工具调用会自动重连。

命令行

node winchrome.mjs start                 # 启动调试浏览器（独立 profile）
node winchrome.mjs status                # 探测结果 + 端口/端点状态
node winchrome.mjs tools                 # 列出 chrome-devtools-mcp 的全部工具
node winchrome.mjs daemon status         # CLI 加速守护进程（start / stop）
node winchrome.mjs pages                 # 列出页面
node winchrome.mjs goto https://x.com    # 导航
node winchrome.mjs snap                  # 无障碍树快照（拿 uid）
node winchrome.mjs click 1_29            # 按 uid 点击
node winchrome.mjs type "你好"            # 在当前焦点输入
node winchrome.mjs search "关键词"        # 快照→找输入框→填词→回车（同一次会话）
node winchrome.mjs eval 'document.title' # 页面内执行 JS
node winchrome.mjs shot out/x.png        # 截图（默认回拷到 WSL）
node winchrome.mjs call fill '{"uid":"1_29","value":"x"}'
node winchrome.mjs seq '[{"name":"take_snapshot"},{"name":"click","args":{"uid":"1_5"}}]'

两点经验：

• uid 只在同一次 MCP 会话内有效。需要「看一页再点」的连续操作，用 seq，或者直接用 MCP 客户端里的原生工具（服务器常驻，uid 天然跨调用有效）。

• CLI 默认走常驻守护进程，所以连续调用很快，也不会反复新建浏览器连接。加 WINCHROME_NO_DAEMON=1 可退回每次新开会话。

• 守护进程会把启动时的参数固化下来（包括 WIN_MCP_EXTRA 等）。改了环境变量后先跑 node winchrome.mjs daemon stop，下次调用才会按新参数重新拉起。

环境变量

全部可选，不设就自动探测。

安全须知

这个工具本质上是把浏览器的完整控制权交给 WSL 里的程序，请知悉：

• 调试端口只绑 127.0.0.1，Windows 防火墙之外访问不到；但仍不要把它暴露到局域网。

• 默认使用独立 profile，里面没有你日常浏览器的 Cookie 和登录态。这是有意的隔离—— 它同时意味着你在里面是「未登录」状态，需要单独登录一次（之后会持久保存）。

• 想接日常 Chrome 的登录态，得先在 chrome://inspect/#remote-debugging 手动开启实例级 远程调试，再把 WIN_CHROME_MODE 设为 auto。代价是每建立一条新连接就弹一次授权框： 这是 Chrome 144+ 的设计，上游 chrome-devtools-mcp#825 请求「记住选择」被 closed as not planned。本项目用常驻守护进程把连接数压到最低（2 条）， 但无法消除该弹窗。

• 不要把带敏感信息的截图提交进仓库（.gitignore 已排除 out/）。

兼容性

• 实测环境：Windows 11 + WSL2（Ubuntu）+ Chrome 154 + Node 22 + chrome-devtools-mcp 1.10.1（30 个工具；1.9.0 为 29 个，1.10.1 新增 get_css_styles）。

• Edge 同样可用（chrome-devtools-mcp 官方支持 Chromium 系浏览器）：把 WIN_CHROME_EXE 指向 msedge.exe。注意 Edge 也继承了 Chrome 136 的默认 profile 限制。

• 不依赖 DSH：任何能执行命令的 MCP 客户端都能用它。

文档

• docs/NOTES.md — 踩坑记录：为什么必须这样绕、实测性能数据、 大截图回拷、工具 schema 开销等。

License

MIT