English | 中文

Windows Chrome DevTools MCP — Hermes Skill

在 WSL2 中通过 chrome-devtools-mcp 连接和控制 Windows Chrome 浏览器，让 AI Agent（Hermes Agent）获得完整的浏览器操控能力。

┌─────────────────────┐     CDP WebSocket      ┌──────────────────────┐
│   WSL2 (Hermes)     │ ◄─────────────────────► │  Windows Chrome      │
│                     │    ws://host:9922        │  --remote-debugging  │
│  Hermes Agent       │                          │  --user-data-dir     │
│    └─ native MCP    │                          │                      │
│       └─ chrome-    │                          │  日常浏览 + 调试用   │
│          devtools   │                          │                      │
└─────────────────────┘                          └──────────────────────┘

Features

• 🖥️ Control real Chrome — not a headless browser, uses your installed Chrome with cookies, extensions, and login state
• 🔧 Full CDP access — navigate, click, type, screenshot, evaluate JS, get console/network logs
• 🔗 Works with WSL2 — NAT and mirrored networking modes both supported
• 🤖 AI-native — designed for Hermes Agent but works with any MCP-compatible client

Quick Start

1. Start Chrome with remote debugging (Windows)

& "C:\Program Files\Google\Chrome\Application\chrome.exe" `
  --remote-debugging-port=9922 `
  --user-data-dir="$env:TEMP\chrome-devtools-mcp-profile" `
  --no-first-run `
  --no-default-browser-check

⚠️ Chrome 136+ requires a non-default --user-data-dir for remote debugging.

2. Verify connectivity (WSL2)

# Mirrored mode
curl http://127.0.0.1:9922/json/version

# NAT mode
HOST_IP=$(ip route show | grep default | awk '{print $3}')
curl "http://${HOST_IP}:9922/json/version"

Expected response includes webSocketDebuggerUrl.

3. Configure Hermes Agent

Edit ~/.hermes/config.yaml:

mcp_servers:
  chrome:
    command: "npx"
    args:
      - "-y"
      - "chrome-devtools-mcp@latest"
      - "--browser-url=http://127.0.0.1:9922"
    timeout: 60
    connect_timeout: 30

NAT mode: replace 127.0.0.1 with the Windows host IP (e.g. 172.30.176.1).

Restart Hermes, then ask:

"帮我打开 https://baidu.com，截图给我看看"

Networking Troubleshooting

Mirrored vs NAT mode

| Mode | Detection | Chrome URL | Easiest setup | |------|-----------|------------|---------------| | Mirrored | ip route shows 127.0.0.1 | http://127.0.0.1:9922 | ✅ Direct | | NAT | ip route shows 172.x.x.x | http://<HOST_IP>:9922 | Need port forward |

NAT mode: port forwarding

Chrome always binds to 127.0.0.1 only (Chrome 148+ drops --remote-debugging-address). Use netsh portproxy on Windows (admin PowerShell):

netsh interface portproxy add v4tov4 listenport=9922 listenaddress=0.0.0.0 connectport=9922 connectaddress=127.0.0.1

Also add a firewall rule:

New-NetFirewallRule -DisplayName "Chrome DevTools MCP" -Direction Inbound -Protocol TCP -LocalPort 9922 -Action Allow

WSL Interop (for scripts)

If start-chrome.sh fails with cannot execute binary file, WSL Interop is disabled. Either:

1. Enable it in %USERPROFILE%\.wslconfig: interopEnabled=true, then wsl --shutdown
2. Or start Chrome manually on Windows (see Quick Start step 1)

Mid-session socat workaround

If Hermes is already running with 127.0.0.1:9922 and you can't restart:

HOST_IP=$(ip route show | grep default | awk '{print $3}')
socat TCP-LISTEN:9922,bind=127.0.0.1,fork,reuseaddr TCP:${HOST_IP}:9922 &

Available MCP Tools

Once connected, chrome-devtools-mcp provides tools prefixed with mcp_chrome_:

| Tool | Function | |------|----------| | mcp_chrome_navigate_page | Navigate to URL | | mcp_chrome_take_screenshot | Screenshot page or element | | mcp_chrome_click | Click element by uid | | mcp_chrome_fill | Fill input / select option | | mcp_chrome_fill_form | Fill multiple form elements at once | | mcp_chrome_evaluate_script | Execute JavaScript | | mcp_chrome_take_snapshot | Get page a11y tree snapshot | | mcp_chrome_list_console_messages | Get console logs | | mcp_chrome_list_network_requests | Get network request logs | | mcp_chrome_performance_start_trace | Performance trace recording | | mcp_chrome_lighthouse_audit | Lighthouse accessibility/SEO audit | | And more... | |

License

MIT