Remote Browser MCP

简体中文 · Security · Contributing · Phase 1 · Phase 2

Connect an AI assistant to your already-running Microsoft Edge or Google Chrome via Chrome DevTools MCP and an optional persistent OpenAI tunnel. Reuse existing login sessions while protecting the user's original tabs. Supports native Windows, Linux and macOS setup, with legacy WSL2 support, with no custom browser build or headless replacement.

Experimental: The tunnel and MCP runtime can be healthy while the browser's CDP WebSocket is unavailable. Check browser health separately; no guarantee of zero focus changes on arbitrary websites.

Features

• Connects to an existing Edge/Chrome CDP session on loopback port 9222; tries the DevToolsActivePort WebSocket when /json/version is unavailable.

• Supports a persistent MCP process via tunnel-client, without creating a new browser for each request.

• Legacy WSL tunnel auto-recovery via an optional systemd user service; reuses the original tunnel and never restarts Edge.

• Forces new_page into the background and prevents select_page from bringing windows forward.

• Protects pre-existing user tabs by default; new dedicated tabs share the browser profile's authentication.

• Explicit tool allowlist: no raw network inspection, file upload, heap snapshots, arbitrary JavaScript or newly introduced upstream tools by default.

• Read-only browser_status reports CDP readiness without revealing URLs, page titles, or credentials.

• Configuration uses config.example.toml; private overrides in config.toml are gitignored.

Related MCP server: agent-login

One-entry setup (recommended)

Windows: setup.cmd · Linux: sh setup.sh · macOS: setup.command or sh setup.sh. See the Linux/macOS guide or Windows guide.

Download the v0.3.0 release for your platform and verify SHA-256 using SHA256SUMS, then run its setup entry. Or use the version-pinned bootstrap commands below. No Git clone is required. The bilingual wizard installs project dependencies, saves credentials securely, starts the runtime and guides ChatGPT registration. Account login and browser consent remain explicit user steps.

Version-pinned bootstrap

Linux or macOS:

curl -fsSL https://raw.githubusercontent.com/ThinkerQAQ/remote-browser-mcp/v0.3.0/install.sh | sh

Windows PowerShell:

irm https://raw.githubusercontent.com/ThinkerQAQ/remote-browser-mcp/v0.3.0/install.ps1 | iex

The bootstrap verifies the downloaded release archive against the accompanying SHA256SUMS. Node.js and npm dependencies are installed by the setup wizard; your own tunnel credentials and ChatGPT registration still require explicit user action. Do not publish your private tunnel ID or keys.

Manual start (Windows PowerShell)

Requires Node.js 22+ and Edge with remote debugging enabled in edge://inspect.

npm ci
npm run check
npm run doctor
npm run proxy-smoke
npm run mcp

npm run proxy-smoke opens only an about:blank test tab, verifies protections and closes that test tab. npm run mcp runs the guarded local MCP server over stdio. It does not create a remote plugin or publish a public CDP endpoint.

Remote access from ChatGPT

Use the phase-two guide to connect your own dedicated OpenAI tunnel through the managed local runtime and create a private ChatGPT plugin using the tunnel ID. Keep all identifiers, keys, browser profiles, and user-specific plugin manifests out of this repository. Tunnel readiness does not guarantee the Edge CDP WebSocket is working; call browser_status first.

Skill loading does not prove MCP tool discovery. Register and test the MCP connection separately from skill packaging. Imported MCP bundles may be Desktop only; see registration and troubleshooting. If upstream discovery fails, only browser_status is advertised; refresh the connection after recovery.

Limitations

• Connects to configured Edge/Chrome debugging sessions. Unix setup can explicitly launch a dedicated automation profile; it never silently restarts user windows.

• Background mode is best effort; real websites can open native dialogs and alter focus.

• Persistent tunnel, browser CDP and ChatGPT plugin are distinct layers with separate health states and authorization requirements.

• The safe default does not operate existing user tabs. Explicit opt-in is required for that mode.

• Local browser access is sensitive; inspect SECURITY.md before enabling a remote plugin.

Built on Chrome DevTools MCP and the Model Context Protocol SDK. Original integration code is licensed under Apache-2.0; upstream packages retain their own licenses. See third-party notices for pinned dependencies and redistribution obligations.