web-bridge
web-bridge-mcp is a relay MCP server that lets an AI editor browse, inspect, script, and interact with any static web page that embeds client.js, using either HTTP or stdio transport.
list_pages — List all connected browser pages (pageId, title, URL, connected time).
eval_js — Execute arbitrary JavaScript in a page, with
awaitsupport and helpers like$/$$,$deep/$$deep,$import,$wait,$frame,$rect, and$css.get_console — Read recent console logs and uncaught errors, with optional incremental fetching via
since.click / type / hover / focus / scroll_to — Interact with page elements using deep CSS selectors (piercing shadow DOM).
wait_for — Poll until a selector appears/disappears or a JS predicate holds, essential for SPAs.
get_text — Read innerText from the page or a specific element.
get_dom_snapshot — Get a text-based “virtual screenshot” of an element subtree, including geometry and computed styles, without needing permissions.
get_screenshot — Capture a real rendered JPEG screenshot (requires one-time browser display-capture authorization).
Supports local stdio mode and remote HTTP mode, plus optional admin console/group isolation for multi-project or shared deployments.
Pages auto-reconnect and show a status bubble with an operation log, so humans can see what the AI did.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@web-bridge List the connected pages, then click the #btn button and read the console output."
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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 # 首次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>Configure the MCP service in your AI editor: replace
<REPO>/server.jsin mcp.json with the absolute path to this repository, and paste it as described for your editor below. As soon as the editor startsserver.js, the WebSocket service (default127.0.0.1:3210) is ready.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 connected pages (pageId, title, URL, connection time) |
|
| Execute arbitrary JS on the page and return a serialized result; supports |
| optional | Read the page's recent console output and uncaught exceptions |
|
| Find the element and trigger click() (scrollIntoView first) |
|
| Focus, write text, dispatch input / change events (compatible with contenteditable) |
| optional | 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 detectsX-Forwarded-Proto/X-Forwarded-Hostand generates the correctwss://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
/mcpendpoint 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 |
|
| 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 |
|
| Reported after connection, on DOMContentLoaded/load/popstate/hashchange, and via a 5s polling fallback (for SPAs) |
Page→Server |
|
| 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 |
|
| Late responses (already timed out) are ignored |
Server→Page |
|
| hello validation passed |
Server→Page |
|
| Code to be executed |
Server→Page |
|
| 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; runnpx playwright install chromiumbefore 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 toolsclick点击页面元素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
Scored across 13 tools
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.
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.
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.
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
Related MCP Connectors
MCP server that lets your AI assistant build and deploy apps, hosting each one at a live URL.
Official Browserless MCP server: browser automation, scraping, screenshots and PDFs for AI agents.
Hosted Web Crawler MCP server for Claude, ChatGPT and Cursor, with each action switched per account.
Turn any public website into an MCP server for agents to search, read and navigate.
Related MCP Servers
- AlicenseBqualityDmaintenanceAn 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.9911 npm3Apache 2.0
- FlicenseBqualityDmaintenanceAn MCP server that enables AI coding tools to control a browser for automated actions, UI extraction, network interception, and screenshots.231-
- AlicenseNot gradedqualityDmaintenanceAn MCP server for browser automation and console log capture via a Chrome extension, enabling AI-driven DOM interaction, navigation, and screenshot capabilities.2MIT
- AlicenseAqualityCmaintenanceMCP server that gives AI coding assistants direct access to the browser — navigate, click, fill forms, run JavaScript, take screenshots, and read page content.1175 npm1MIT