Skip to main content
Glama

web-bridge — An MCP tool that lets AI editors control arbitrary static web pages

web-bridge is an MCP Server (a single Node process with dual interfaces) that lets AI editors execute JavaScript, read the console, and simulate clicks / input on static web pages that include client.js. It is suitable for local cross-browser, multi-tab debugging, and can also be deployed to a public server (--transport http, see “Remote Deployment” below).

   AI 编辑器                ┌───────────────────┐              浏览器页面
┌──────────────┐           │    MCP Server     │           ┌──────────────────┐
│  MCP Client  │           │  (Node 单进程)    │           │ <script src=     │
│              │ stdio 或   │ · 接口B: MCP       │  WebSocket │  :3210/client.js">│
│  AI 只到这里  │◄─────────►│   (stdio / http)  │◄──────────►│  client.js       │
└──────────────┘  Streamable│ · 接口A: WebSocket │  接口A     │  (eval 执行/     │
      HTTP(远程)           │ · HTTP /client.js │            │   console 捕获)  │
                           └───────────────────┘            └──────────────────┘

The AI editor and the browser are not directly connected: both connections terminate at the MCP Server (server.js), and the AI indirectly controls the page through tool calls.

Quick Start

cd web-bridge
npm install          # 首次
  1. Include the script in a static web page (any page, any port, cross-origin allowed):

    <script src="http://127.0.0.1:3210/client.js"></script>
  2. Configure the MCP service in your AI editor: replace <REPO>/server.js in mcp.json with the absolute path to this repository, and paste it as described for your editor below. As soon as the editor starts server.js, the WebSocket service (default 127.0.0.1:3210) is ready.

  3. Tell the AI: “Use web-bridge's list_pages to see which pages are connected, then use eval_js to click #btn and read the console.”

Load order note: it doesn't matter if the page loads it first; client.js will automatically reconnect (1s→2s→5s→10s backoff), and the page will reattach automatically after the editor starts. Hub status page: http://127.0.0.1:3210/

Related MCP server: browser-mcp

MCP Tools

Tool

Parameters

Description

list_pages

—

List connected pages (pageId, title, URL, connection time)

eval_js

code, optional pageId / timeoutMs

Execute arbitrary JS on the page and return a serialized result; supports await; the last expression is returned automatically, statement blocks can use return; $ / $$ (querySelector / querySelectorAll) are predefined

get_console

optional pageId / limit

Read the page's recent console output and uncaught exceptions

click

selector, optional pageId

Find the element and trigger click() (scrollIntoView first)

type

selector / text, optional pageId

Focus, write text, dispatch input / change events (compatible with contenteditable)

get_text

optional selector (default body), pageId

Read the element's innerText

pageId rule: can be omitted when only one page is connected; when multiple pages are connected and none is specified, the tool returns an error and a list of pages, and the AI will retry with pageId added.

Editor integration

The examples below assume the repository's absolute path is /path/to/web-bridge; replace it as needed.

ZCode / Claude Code (project root .mcp.json, or claude mcp add):

{
  "mcpServers": {
    "web-bridge": {
      "command": "node",
      "args": ["/path/to/web-bridge/server.js"],
      "env": { "PORT": "3210" }
    }
  }
}

Cursor (.cursor/mcp.json): same format as above.

Claude Desktop (claude_desktop_config.json): same format as above.

Command-line arguments: node server.js --port 3210 --host 127.0.0.1 --token <secret> (environment variables PORT / HOST / TOKEN can also be used).

Remote deployment (public server)

The default stdio mode requires the editor to start the process locally; to deploy web-bridge to a public server, switch to HTTP transport mode, and the editor only needs to fill in a url in the MCP configuration:

1. Start it on the server (systemd / pm2 recommended; a token is required on the public internet):

node server.js --transport http --host 0.0.0.0 --port 3210 --token <secret>

2. Editor configuration (Claude Code / Cursor / ZCode, etc., paste it in the original config location):

{
  "mcpServers": {
    "web-bridge": {
      "type": "http",
      "url": "https://your-domain.com/mcp",
      "headers": { "Authorization": "Bearer <secret>" }
    }
  }
}

For a direct connection (no reverse proxy / TLS), set url to http://<服务器IP>:3210/mcp. Note: Claude Desktop only supports local stdio mode, not a remote url.

3. Change the page-side script to point to the server:

<script src="https://your-domain.com/client.js?token=<secret>"></script>

Notes:

  • HTTPS pages can only connect to https/wss (mixed content restriction). It is recommended to use a reverse proxy such as nginx / caddy to terminate TLS and forward to this service; when client.js is served, it automatically detects X-Forwarded-Proto / X-Forwarded-Host and generates the correct wss:// connection address, no extra configuration needed. caddy example (automatic certificate signing):

    your-domain.com {
      reverse_proxy 127.0.0.1:3210
    }
  • After a token is enabled, the /mcp endpoint supports three authentication formats: Authorization: Bearer <secret> (recommended; set headers in the editor configuration), X-Web-Bridge-Token: <secret>, and the url parameter ?token=.

  • The HTTP transport uses the official Streamable HTTP protocol (stateless mode); each request is handled independently and shares the same hub, so multiple editors can connect simultaneously.

  • For public deployment, be sure to: set --token, use TLS, and allow only the needed ports in the firewall.

Security notes

  • By default it listens only on 127.0.0.1. Any web page open on this machine (including third-party sites you browse) can try to connect to the local port — in the default no-token mode, they can receive code sent by the AI and also forge results.

  • In untrusted network environments, or when you want devices on the LAN such as phones to connect (--host 0.0.0.0), be sure to enable --token: in this case, fetching client.js requires ?token=<secret>, and the first WebSocket packet also validates the token.

WebSocket message protocol (internal reference)

The WS messages between the browser and the MCP Server are all JSON text frames; refer to this when maintaining lib/hub.mjs / client.js:

Direction

Message

Fields

Description

Page→Server

hello

role:"page", pageId, url, title, ua, token?

First packet after connecting; disconnected if not received within 5 seconds; when pageId is duplicated (duplicate tab), the new connection replaces the old one

Page→Server

page-info

url, title

Reported after connection, on DOMContentLoaded/load/popstate/hashchange, and via a 5s polling fallback (for SPAs)

Page→Server

console

level, text, ts

Console wrapper and uncaught exception capture, batched with 500ms throttling; hub keeps a ring buffer of 500 messages per page (retained after disconnection)

Page→Server

eval-result

reqId, ok, value?, error?, durationMs

Late responses (already timed out) are ignored

Server→Page

welcome

pageId

hello validation passed

Server→Page

eval

reqId, code, timeoutMs

Code to be executed

Server→Page

error

error

e.g. token error

eval execution conventions (client.js): first wrap as an expression async () => ( code ); on SyntaxError, fall back to a statement block (return allowed); $ / $$ are predefined; timeout is tracked on the hub side (default 30s, max 120s); results are safely serialized as a string preview (Error→stack, DOM→outerHTML summary, circular reference markers, depth ≤ 6, ≤ 50k characters).

Development

  • Testing: npm test (Node e2e: start process + simulated page + call tools over both stdio/HTTP transports); npm run test:browser (Playwright real-browser flow: Chromium loads test/test-page.html, verifies the 6 tools over a real WebSocket; run npx playwright install chromium before the first time). The real-browser flow can also be verified manually by opening the test page.

  • Dependencies: ws (WebSocket), @modelcontextprotocol/sdk (MCP), zod (parameter validation); dev dependency @playwright/test. Node ≥ 18.

Available Tools

13 tools
click点击页面元素A

通过 CSS 选择器找到元素并触发 click()(会先 scrollIntoView)。找不到元素时返回错误。

Inputs: selector (required), note, pageId.

eval_js在页面执行 JavaScriptA

在指定页面(pageId 省略且只连了一页时自动选中)执行任意 JavaScript 并返回序列化结果。支持 await 与多语句;最后一句表达式会被自动 return,也可显式 return。预置 $ / $$(普通查询)、$deep / $$deep(穿 shadow DOM 深度查询)、$import(页面路径动态 import)、$wait(轮询等条件,函数或选择器字符串,第二参为超时 ms)、$frame(同源 iframe 查询辅助,返回 {$,$$,$deep,$$deep,document,window})、$rect(元素几何+可见性)、$css(批量写样式)。

Inputs: code (required), note, pageId, timeoutMs.

focus聚焦页面元素A

通过 CSS 选择器找到元素并聚焦(focus + focusin),适合输入前把焦点放到指定输入框。

Inputs: selector (required), note, pageId.

get_console读取页面控制台日志A

读取页面最近的 console 输出与未捕获异常(client.js 会自动捕获上报)。limit 为返回条数(默认 50);传 since(毫秒时间戳)则只返回该时间之后的日志(增量拉取),返回末尾会附上最新一条的 ts,可作为下次调用的 since 继续拉取,用于区分修改代码前后的日志。

Inputs: limit, since, pageId.

get_dom_snapshot获取 DOM 样式快照A

对指定元素的子树生成「虚拟截图」:每个可见节点一行,含几何(rect)、关键 computed style(颜色/背景/字号/边框/圆角/阴影/透明度/z-index/溢出)、文本,穿 shadow DOM。纯文本、无需任何授权,是验证颜色、布局、定位的首选;需要真实渲染像素(canvas 内容、图片、遮挡观感)时再用 get_screenshot。

Inputs: selector (required), note, depth, pageId, +1 more.

get_guide获取本工具完整使用指南A

返回 web-bridge-mcp 的完整使用指南(SKILL.md 全文,含标准工作流、eval_js 写法、预置函数、排错表与踩坑经验)。首次使用本 MCP 的工具前建议先调用它;指南文件更新后无需重启,再次调用即读到最新版。

Inputs: no named parameters.

get_screenshot真实截图(需用户授权一次)A

通过浏览器屏幕捕获(getDisplayMedia)截取真实渲染像素并返回图片。首次调用会在用户浏览器弹出原生授权框(预选当前标签页),用户授权一次后本次页面生命周期内免打扰;页面刷新后需重新授权。传 selector 时按该元素矩形裁剪(深度查询,穿 shadow DOM)。验证颜色/布局/定位请优先用 get_dom_snapshot(文本、免授权、精确到值);本工具用于需要真实像素的场景(canvas、图片、遮挡观感)。

Inputs: note, pageId, selector, timeoutMs.

get_text读取页面文本A

读取匹配 CSS 选择器元素的 innerText;selector 省略时读取整个 body。

Inputs: note, pageId, selector.

hover悬停页面元素A

通过 CSS 选择器找到元素并派发 mouseover / mouseenter(可触发菜单、tooltip 等悬停行为),会先 scrollIntoView。

Inputs: selector (required), note, pageId.

list_pages列出已连接页面A

列出当前通过 client.js 连接到 web-bridge-mcp 的所有浏览器页面(pageId、标题、URL、连接时间)。

Inputs: no named parameters.

scroll_to滚动到页面元素A

通过 CSS 选择器找到元素并滚动到可视区域中央(scrollIntoView),返回滚动后的位置信息。

Inputs: selector (required), note, pageId.

type向输入框输入文本A

通过 CSS 选择器找到输入元素,聚焦并写入文本,随后派发 input / change 事件(兼容 contenteditable)。

Inputs: text (required), selector (required), note, pageId.

wait_for等待页面条件成立A

在页面上轮询等待条件成立后再返回,避免 SPA 异步渲染导致「元素还没出来就操作」。两种条件二选一:selector(元素出现;absent=true 时改为等待其消失)或 code(返回真值的 JS 表达式,支持 await)。超时仍未满足则报错。轮询间隔 200ms。

Inputs: code, note, absent, pageId, +2 more.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.1/5.0

    Scored across 13 tools

    Disambiguation5/5

    Each tool targets a distinct action or read: list_pages enumerates contexts, get_guide is meta-documentation, eval_js is the generic execution escape hatch, and click/type/hover/focus/scroll_to cover specific interactions. Although eval_js could technically perform many of the specialized operations, the specialized tools have clearly separated purposes and the descriptions reinforce the boundaries.

    Naming Consistency4/5

    Names are uniformly lowercase and follow a readable functional pattern: get_* for state/read operations, bare verbs for direct actions, and wait_for/scroll_to for prepositional actions. Minor deviations from a strict verb_noun convention (click, type, wait_for) are not confusing but prevent a perfect score.

    Tool Count5/5

    Thirteen tools is well-scoped for a browser-automation bridge: discovery, execution, console access, DOM reading, waiting, interaction, and two complementary visual verification tools. Each tool has a distinct role and none feels redundant or missing in the immediate set.

    Completeness4/5

    The surface covers the core browser workflow well: list pages, execute JS, read logs/text, wait for conditions, interact, focus, scroll, and verify via DOM or screenshot. There is no dedicated navigation, keyboard, or page-lifecycle tool, but eval_js and the existing interaction tools provide reasonable workarounds for those gaps.

    Maintenance

    ActivityStale
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      B
      quality
      D
      maintenance
      An MCP server that provides AI models with full browser automation capabilities through Chrome. It enables navigation, interaction, screenshots, and complete DevTools access by bridging AI clients with a companion Chrome extension.
      99
      11 npm
      3
      Apache 2.0
    • F
      license
      B
      quality
      D
      maintenance
      An MCP server that enables AI coding tools to control a browser for automated actions, UI extraction, network interception, and screenshots.
      23
      1
      -
    • A
      license
      Not graded
      quality
      D
      maintenance
      An MCP server for browser automation and console log capture via a Chrome extension, enabling AI-driven DOM interaction, navigation, and screenshot capabilities.
      2
      MIT
    • A
      license
      A
      quality
      C
      maintenance
      MCP server that gives AI coding assistants direct access to the browser — navigate, click, fill forms, run JavaScript, take screenshots, and read page content.
      11
      75 npm
      1
      MIT