Skip to main content
Glama
beifangzhishi-ops

Browser MCP Gateway

by beifangzhishi-ops
OverviewSchemaSourceRelated ServersScoreDiscussionsAdmin
JavaScript
Local

Browser MCP Gateway

Windows gateway around hangwin/mcp-chrome for using an existing Microsoft Edge session from ChatGPT through an OAuth-protected HTTPS endpoint such as Tailscale Funnel.

This repository wraps the upstream project, adds Microsoft Edge Native Messaging registration on Windows, and exposes it through an independent local OAuth sidecar.

BMG OAuth sidecar

当前正式并行架构如下：

ChatGPT
    |
    | OAuth + MCP
    v
https://your-machine.your-tailnet.ts.net/bmg/mcp
    |
    v
127.0.0.1:18007  BMG OAuth sidecar
    |
    v
127.0.0.1:12306  upstream mcp-chrome
    |
    v
Edge Native Messaging + extension

sidecar 只绑定 127.0.0.1:18007，不修改 upstream mcp-chrome 核心实现，也不拥有 Edge 或 12306 的生命周期。其 issuer 是 https://your-machine.your-tailnet.ts.net/bmg，resource 是 https://your-machine.your-tailnet.ts.net/bmg/mcp。OAuth state、upstream session state、approval secret、日志和 config/.env 均由 BMG 独立保存。access token 默认 1 小时有效；授权码兑换会同时签发 30 天 refresh token，refresh token 每次使用都会轮换，为新会话或 access token 过期后的无人工批准续期提供凭证。

启用并启动 sidecar：

.\scripts\enable-oauth.ps1 -PublicBaseUrl https://your-machine.your-tailnet.ts.net
.\scripts\start.ps1

安装当前用户登录自启（不需要管理员权限，只启动 BMG sidecar，不管理 Tailscale、12306 或 Edge）：

.\scripts\install-autostart.ps1

如需移除：

.\scripts\uninstall-autostart.ps1

停止 sidecar 只校验 BMG PID file、18007 精确 loopback listener 和本地 health，不会停止 12306、Node、Edge 或 Native Messaging：

.\scripts\stop.ps1

本地端到端检查（需要 upstream 12306 和 Edge extension 已运行）：

node scripts\test-bmg-e2e.mjs

该检查连续运行两轮 OAuth/PKCE，并验证两轮共享同一个 upstream MCP session。每轮的下游 DELETE 只关闭客户端视角的 session，不会关闭共享 upstream transport；sidecar 停止时关闭自身监听并保留该 session 的非敏感元数据，重启后继续复用。这样兼容 upstream 的 singleton transport 生命周期。

文件传输：在 workspace 模式下，BMG 会补充暴露 upstream 已实现但默认 tools/list 未列出的 chrome_upload_file 和 chrome_handle_download。上传应优先使用 chrome_upload_file 直接通过 CDP DOM.setFileInputFiles 设置 ，避免点击控件后弹出 Windows 文件选择器；chrome_handle_download 用于等待浏览器管理的下载并返回最终本机文件路径、状态和大小。Windows 原生 File System Access / Save As 对话框不属于这两个工具的控制范围，必要时使用 mg_show_workspace 进行人工处理。

configure-funnel.ps1 和 disable-funnel.ps1 默认只输出预览；本阶段不实际修改 Tailscale Funnel。未来若明确需要应用，才显式使用 -Apply，脚本也只处理 BMG 自己的精确 OAuth/MCP 路径。

Architecture

ChatGPT Web
    |
    | OAuth + HTTPS / MCP
    v
Tailscale Funnel
    |
    v
https://your-machine.your-tailnet.ts.net/bmg/mcp
    |
    v
127.0.0.1:18007  BMG OAuth sidecar
    |
    | local HTTP proxy
    v
127.0.0.1:12306  upstream mcp-chrome
    |
    | Native Messaging
    v
Edge extension + normal Edge tabs

sidecar、upstream、Native Messaging 和 Edge extension 分属独立生命周期。BMG 不启动浏览器、不使用 CDP 端口、不创建专用浏览器 profile，也不修改 upstream 核心实现。

Upstream versions currently pinned

  • Source: hangwin/mcp-chrome commit f48e71751e00bc09725c7e173423cff4f2ccd12a

  • Native bridge: mcp-chrome-bridge@1.0.29

  • Extension release: v1.0.0

  • Extension archive SHA256: e0f7edfe84b64fd452deec048fc202cfa33585943da63a06c08e2bbc97770f6a

The source checkout is kept under ignored upstream/mcp-chrome/ for inspection only. Runtime uses the upstream npm bridge package and release extension rather than a locally modified fork.

Requirements

  • Windows 10/11

  • Microsoft Edge

  • Git

  • Node.js 20+

  • npm

  • Tailscale with Funnel enabled for this device/tailnet

Install

If GitHub CLI already works on your machine, the easiest clone command is:

gh repo clone beifangzhishi-ops/browser-mcp-gateway
cd browser-mcp-gateway

Plain Git also works when Git itself has network access:

git clone https://github.com/beifangzhishi-ops/browser-mcp-gateway.git
cd browser-mcp-gateway

Then run:

.\scripts\setup.ps1

or double-click:

安装.cmd

Setup will:

  1. Verify GitHub CLI authentication and resolve the configured npm proxy.

  2. Install mcp-chrome-bridge@1.0.29 globally with npm.

  3. Register the installed Native Messaging host directly for Microsoft Edge.

  4. Download and SHA256-verify the pinned upstream extension release into extension/.

It does not register or configure Google Chrome.

Windows 命令说明

仓库脚本在 Windows 上显式调用 gh.exe、node.exe、npm.cmd 和 mcp-chrome-bridge.cmd，避免 PowerShell 执行策略拦截 npm 生成的 .ps1 shim；当 PATH 中存在多个同名程序时取第一个匹配项，状态.cmd 会直接显示这些程序的版本。当前仓库固定的 mcp-chrome-bridge@1.0.29 提供 register、fix-permissions 和 update-port，不包含 doctor 子命令；排查时不要直接运行 mcp-chrome-bridge.ps1。新版桥接包可能引入需要本机编译的原生依赖，升级前应先确认 Node.js 版本兼容性。

Proxy handling

setup.ps1 automatically tries to make command-line downloads follow the same Windows proxy/PAC route used by desktop applications.

Proxy priority is:

  1. -Proxy parameter

  2. BROWSER_MCP_PROXY environment variable

  3. existing HTTPS_PROXY / HTTP_PROXY environment variables

  4. Windows system proxy/PAC resolved separately for GitHub and npm

The resolved proxy is injected only into the setup process for Git, npm, and the extension download. It is not written into your global Git or npm configuration.

CI checks the Windows target-specific proxy lookup and npm handoff behavior directly, rather than requiring a particular helper function name.

Examples:

.\scripts\setup.ps1 -Proxy http://127.0.0.1:7890

or:

$env:BROWSER_MCP_PROXY = "http://127.0.0.1:7890"
.\安装.cmd

When auto-detection works, setup prints a line such as:

Network route for https://github.com/ : http://127.0.0.1:7890 [Windows system proxy/PAC]

Load the extension in Edge

  1. Open Edge normally from the desktop/taskbar.

  2. Visit edge://extensions/.

  3. Enable Developer mode.

  4. Click Load unpacked.

  5. Select this repository's extension directory.

  6. Open the extension and connect it to the native bridge.

The upstream Native Messaging host name is com.chromemcp.nativehost. The default extension ID expected by upstream is hbdgbgagpkpjffpklnamcljpakneikee.

If Edge shows a different unpacked extension ID, rerun:

.\scripts\register-edge.ps1 -ExtensionId YOUR_EDGE_EXTENSION_ID

After the extension connects, the upstream MCP endpoint should be:

http://127.0.0.1:12306/mcp

Tailscale Funnel

After the Edge extension is connected, local port 12306 is listening, and the sidecar health is 200, use an elevated PowerShell only when a Funnel change is explicitly approved:

.\scripts\configure-funnel.ps1
.\scripts\configure-funnel.ps1 -Apply

The first command is preview-only. The second command applies only the BMG route list. The ChatGPT custom MCP server URL is https://your-machine.your-tailnet.ts.net/bmg/mcp.

Status

.\scripts\status.ps1

This checks Node/npm, the installed bridge, Edge Native Messaging registration, local MCP port 12306, and Tailscale Funnel status.

Important security note

GPT dedicated browser workspace

Set BMG_WORKSPACE_MODE=1 in the local ignored config/.env to pin page-directed MCP tools to one BMG-owned Edge window/tab. The sidecar creates the workspace window unfocused, persists only its non-sensitive windowId/tabId plus the exact Win32 hwnd under .state/bmg-workspace.json, and injects those IDs into upstream tool calls. Navigation stays in that workspace and chrome_close_tabs is narrowed to the workspace tab, so normal foreground Edge windows are not selected by default.

The workspace window is intentionally still a normal user-profile Edge window so it shares the user's existing login state. BMG keeps it unfocused, moves the dedicated workspace window off-screen, and marks it as a Win32 tool window so it stays out of the normal taskbar/Alt-Tab app list while remaining normally rendered for screenshots. Read-only global tools such as history/bookmarks/window listing are not window-scoped. When manual login, QR scanning, CAPTCHA, or verification is required, bmg_show_workspace restores that exact tracked HWND to a normal foreground Edge window without changing its tab or profile; bmg_hide_workspace returns the same window to off-screen tool-window mode. The explicit visible/hidden state is persisted across sidecar restarts.

The upstream project exposes powerful browser capabilities. BMG therefore keeps the upstream listener local and requires the sidecar OAuth layer before forwarding any MCP request.

Treat the public MCP URL as a privileged automation endpoint even though OAuth is required. Keep the upstream listener bound to localhost, protect the public route with the sidecar, and avoid exposing any unprotected browser-control port. The generated OAuth state, approval secret, workspace state, logs, and config/.env are local-only and must not be committed.

Why this repository exists

mcp-chrome already provides the mature browser integration: tabs, existing login state, page extraction, interactions, screenshots, network tools, history/bookmarks, and Streamable HTTP MCP. The only local glue needed for this setup is:

  • Edge Native Messaging registration on Windows (upstream currently registers Chrome/Chromium only)

  • repeatable installation/version pinning

  • automatic Windows proxy/PAC handoff for setup

  • Tailscale Funnel configuration

That keeps this repository small and makes upstream updates replaceable instead of maintaining another browser automation implementation.

License

This repository is licensed under the MIT License. Upstream components such as hangwin/mcp-chrome retain their own copyright notices and licenses; the pinned upstream project is also MIT-licensed.