quark-browser-mcp

An MCP server that drives the Quark browser you're already logged into, over the Chrome DevTools Protocol.

Zero dependencies — node:http for the transport, Node 22+ global WebSocket for CDP.

node server.mjs --http 9311        # streamable HTTP at http://127.0.0.1:9311/mcp
node server.mjs                    # or stdio

中文说明见下方 中文。

Why

Most browser MCP servers launch a fresh Chrome profile, so you're logged out of everything.

This one attaches to a running Chromium browser that already has your cookies, sessions and extensions — so an agent can act as you on sites you're signed in to, without a login dance every time.

It was built for the Quark PC client (a Chromium 144 derivative), but the protocol is plain CDP, so any Chromium with --remote-debugging-port works: Chrome, Edge, Brave, CentBrowser, …

Related MCP server: BrowserUse

Requirements

• Node.js 22+ (for the built-in WebSocket)

• A Chromium-based browser started with a debugging port:

your-browser.exe --remote-debugging-port=9223

Verify: curl http://127.0.0.1:9223/json/version should return JSON.

Run

git clone <this repo>
cd quark-browser-mcp

# HTTP transport (easiest for MCP clients that take a URL)
node server.mjs --http 9311

# stdio transport
node server.mjs

Environment:

Register with any MCP client:

# Claude Code
claude mcp add --transport http quark-browser http://127.0.0.1:9311/mcp

For clients that only speak stdio, point them at node /path/to/server.mjs.

Tools

Typical session:

browser_open     {"url":"https://music.163.com"}
browser_snapshot {}
browser_type     {"ref":3,"text":"周杰伦"}
browser_press    {"key":"Enter"}
browser_click    {"ref":7}

Design notes

• The snapshot is the addressing scheme. Every snapshot rewrites data-qb-ref on the elements it returns, so old refs die immediately. The model has to look before it acts — no stale CSS selectors.

• Click scrolls first. scrollIntoView({block:'center'}), then dispatch mousedown/mouseup/click at the element's centre, so lazy-loaded and half-visible targets still work.

• Typing uses the native setter. HTMLInputElement.prototype's value setter plus input/change events — React and Vue controlled components see it as real input.

• Snapshot comes back with the action. Click returns the resulting page state in the same call, which halves the round trips.

Tested

Target: Quark PC 7.4.9.1045, Chrome/144.0.7559.86.

GET  /health                 → {"ok":true,"cdp":"http://127.0.0.1:9223"}
initialize                   → protocolVersion 2025-06-18
tools/list                   → 8 tools
browser_tabs                 → 8 real tabs
browser_open example.com     → new tab id=01D07EA3…
browser_snapshot             → URL/TITLE/REFS:1 → [1] a "Learn more" -> https://iana.org/…
browser_eval document.title  → "Example Domain | https://example.com/"
browser_type   {ref:1}       → typed into [1] input
browser_click  {ref:2}       → clicked [2] button
verify        document.title  → "clicked:hello-mcp"     ← page JS really ran

Security

The debugging port is full control of the browser, including every logged-in session.

• Keep it on 127.0.0.1; never expose it on a LAN interface or forward it publicly.

• If you need it from another machine, tunnel it (ssh -L 9223:127.0.0.1:9223 …).

• Chromium only binds the debugging port to loopback by default — keep it that way.

Roadmap

• screenshot tool (Page.captureScreenshot) for vision models

• explicit tab switch / close tools

• optional ref-less coordinate clicking

License

MIT

中文

给 MCP 客户端一套浏览器工具，直接操作你已登录的浏览器：列标签页、导航、文本快照（带 [n] 编号）、 点击、输入、按键、执行 JS。零依赖，只要 Node 22+。

和大多数浏览器 MCP 的区别：它们会新起一个干净的 Chrome（所以什么都没登录）， 这个只是附加到你正在跑的那个 Chromium 上，cookie、登录态、插件全在。

要求浏览器带调试端口启动：

your-browser.exe --remote-debugging-port=9223
curl http://127.0.0.1:9223/json/version     # 有 JSON 就成

运行：

node server.mjs --http 9311     # 流式 HTTP：http://127.0.0.1:9311/mcp
node server.mjs                 # 或 stdio

设计要点：

• 快照即寻址：每次快照重排 data-qb-ref，旧编号立刻失效，逼模型"先看再点"，不用 CSS selector；

• 点击先滚动：scrollIntoView 后按元素中心派发事件，懒加载/半可见目标也能点中；

• 输入走原生 setter：React / Vue 受控组件也会当成真实输入；

• 动作默认回带快照：一次调用拿到"点了 + 现在长什么样"，少一轮往返。

安全：调试端口等于整个浏览器的控制权（含所有登录态），只留 127.0.0.1，要跨机就 SSH 隧道。