Browser Pilot

Let ChatGPT work in your browser while you keep using your own tabs.

Features · Setup · Chrome extension · Development · Limits

Browser Pilot connects a Chrome Manifest V3 extension to a remote MCP server hosted on Cloudflare. ChatGPT can read pages, inspect screenshots, fill fields and interact with authorized web tabs through native Chrome DevTools Protocol commands.

New tabs open in the background. Browser Pilot marks tabs it actually controls with its own favicon, and restores the original icon after inactivity. Your current tab does not need to become the automation workspace.

What it does

Capability	Behavior
Background browsing	Create, navigate and interact with tabs without selecting them or bringing their window forward.
Clear ownership	A temporary Browser Pilot favicon identifies controlled tabs; page titles stay intact.
Whole-session access	Access eligible current and future web tabs during a two-hour session, without selecting each tab or a ten-tab permission limit.
Native interactions	Click, type, press keys, select options, scroll and drag through chrome.debugger / CDP.
Visual inspection	Return actual JPEG screenshots as MCP image blocks, plus compact DOM snapshots and element references.
Fast batches	Run up to eight fill/select/click/snapshot steps in one browser_actions call.
Local stop	Stop the session, cancel queued work and detach targets owned by Browser Pilot from the extension popup.
Sensitive actions	Recognized consequential actions request local approval; recognized passwords and CAPTCHAs are blocked.

The Web Bridge Worker includes 21 browser tools alongside public page retrieval, X post retrieval, YouTube search and optional private API provider management. A separate YouTube Transcript Worker is included for transcripts and sampled visual previews.

flowchart LR
    A[ChatGPT / MCP client] -->|OAuth + MCP| B[Your Cloudflare Worker]
    B <-->|Authenticated WebSocket relay| C[Browser Pilot extension]
    C <-->|Native CDP commands| D[Your eligible Chrome tabs]
    D -->|DOM + screenshots| C

Loading

See a real background interaction

The image below is a capture returned by the extension after filling a field, choosing Orange and clicking the result button in an inactive test tab. The exact output was checked independently.

Set up your own instance

Requirements

• Node.js 24, npm and Git.
• A Cloudflare account with Workers, KV and Durable Objects available.
• A GitHub account that can create an OAuth App.
• Chrome 125 or later on the computer you want to control.
• An MCP client that supports remote OAuth servers. In ChatGPT, custom MCP availability depends on your account and workspace settings.

There is no required paid AI API key for Browser Pilot. Cloudflare and upstream services still have quotas; this project does not promise unlimited free operation.

1. Clone and install

git clone https://github.com/Mirochill/browser-pilot.git
cd browser-pilot
cd web-bridge-mcp
npm ci
Copy-Item wrangler.example.jsonc wrangler.jsonc
npx wrangler login
npx wrangler whoami
npx wrangler kv namespace create OAUTH_KV

Use the Cloudflare account that should own this deployment. Keep the pinned dependencies and lockfiles.

2. Configure the Worker

Edit the local, Git-ignored web-bridge-mcp/wrangler.jsonc:

Field	Your value
name	A unique Worker name, such as browser-pilot-yourname.
vars.PUBLIC_ORIGIN	Your Worker HTTPS origin, such as https://browser-pilot-yourname.YOUR-SUBDOMAIN.workers.dev, without a trailing slash or /mcp.
kv_namespaces[0].id	The ID returned by the KV creation command.
account_id	Optional: your intended Cloudflare account ID, especially if you use multiple accounts.

Keep the supplied BROWSER_RELAY Durable Object binding and browser-pilot-v1 SQLite migration. They are required for the browser relay. The template contains no deployment belonging to another person.

3. Create a GitHub OAuth App

Open GitHub OAuth Apps and create an app:

• Homepage URL: your Worker origin.
• Authorization callback URL: your Worker origin followed by /callback.
• Device flow is not required.

This callback is GitHub → your Worker. ChatGPT's callback is handled separately by the MCP OAuth provider and dynamic client registration.

4. Store secrets and deploy

From web-bridge-mcp, run each command and enter the value at Wrangler's prompt:

npx wrangler secret put GITHUB_CLIENT_ID
npx wrangler secret put GITHUB_CLIENT_SECRET
npx wrangler secret put GITHUB_ALLOWED_LOGIN
npx wrangler secret put ADMIN_PAGE_CODE
npx wrangler secret put API_KEYS_ENCRYPTION_KEY
npm run typecheck
npm run deploy

• Set GITHUB_ALLOWED_LOGIN to your GitHub username. Never leave the Web Bridge allowlist empty for a personal deployment: an empty allowlist allows any GitHub login.
• Use a unique strong ADMIN_PAGE_CODE for the optional /keys provider-management page.
• Generate a fresh 32-byte base64 API_KEYS_ENCRYPTION_KEY and keep a secure backup outside Git. It encrypts optional provider API keys stored in KV.
• Enter credentials directly into Cloudflare. Do not put them in the README, Git commits, tool inputs or public issues.

Confirm the final Worker origin in the deployment output. It must match PUBLIC_ORIGIN, the OAuth homepage and the /callback URL. If necessary, update the local configuration and OAuth app, then deploy again.

5. Connect ChatGPT

In ChatGPT's custom MCP app/plugin/connector interface, add your server:

Setting	Value
Server URL	https://YOUR-WORKER-HOST/mcp
Authentication	OAuth
Client registration	Dynamic Client Registration, when offered
Scopes	mcp:read browser:control

Complete the GitHub login with the username in GITHUB_ALLOWED_LOGIN. Refresh the app's tools if the client has cached an older discovery result.

A 401 before authentication is expected. The response advertises the OAuth protected-resource metadata in WWW-Authenticate; follow that metadata rather than inventing endpoint paths.

Connect Chrome

1. Open chrome://extensions, enable Developer mode, select Load unpacked, and choose this repository's extension folder.
2. Open the Browser Pilot popup. Under Réglages de connexion (connection settings), enter your Worker origin, without /mcp, then click Enregistrer (Save). Accept access to your own relay origin. The public extension starts with a nonfunctional placeholder and has no pre-granted relay host.
3. Ask your connected MCP client: “Pair my browser with Browser Pilot.” The browser_pair tool returns a six-character code, valid for ten minutes.
4. Enter that code in the popup and click Associer (Pair).
5. Enable Autoriser les nouveaux onglets créés par ChatGPT if you want the model to create tabs.
6. Click Démarrer la session (Start session) and wait for En ligne (Online).

The current popup is in French; the English meanings are provided above. Pairing survives a reload. Reload the extension after updating its files; start the session again only if it is stopped.

A session gives the connected client access to eligible ordinary HTTP(S) tabs, including signed-in pages. Internal browser pages, incognito tabs and private/local network destinations are excluded. Use the local Stop control when you want that access to end.

Try this first:

Use Browser Pilot to open https://YOUR-WORKER-HOST/browser/test in the
background. Fill the test text field, select Orange, click Show result,
and inspect a screenshot. Keep my current tab selected.

The fixture buttons are localized: Afficher le résultat means “Show result”.

Optional: YouTube Transcript server

The separate youtube-transcript-mcp-starter folder provides transcript languages, complete transcripts, caching and sampled YouTube visual previews. Deploy it with its own Worker, KV namespace and GitHub OAuth App.

Follow the YouTube setup guide. Connect its /mcp endpoint with OAuth and scope mcp:read. FREETRANSCRIPT_API_KEY is optional; anonymous upstream access is attempted first, and a configured key is used only for the defined retry statuses.

YouTube previews and Browser Pilot screenshots are sampled images. They do not give the model a continuous video/audio stream. Upstream rate limits and anti-bot checks can still prevent access.

Development and tests

npm --prefix web-bridge-mcp ci
npm --prefix youtube-transcript-mcp-starter ci
npm --prefix web-bridge-mcp run typecheck
npm --prefix youtube-transcript-mcp-starter run typecheck
npm test

The included runner covers 257 local checks: engine/DOM 105, indicator 19, extension lifecycle 36, relay 48, MCP tools 30, OAuth 8 and legacy Web Bridge 11. These are mocks, fixed DOM fixtures and SDK checks; they are not 257 real-browser tests.

Native validation also covered 11 interaction/protection checks on 0.2.2, 8/8 background checks on 0.2.3, and two acknowledged real-tab closures on 0.2.3. ChatGPT successfully filled, selected, clicked and inspected a returned image on 0.2.2. Full cross-site parity is not claimed. See validation notes.

Path	Purpose
extension/	Manifest V3 popup, native CDP engine, lifecycle and favicon marker.
web-bridge-mcp/	Deployable Web Bridge Worker, OAuth and browser relay.
youtube-transcript-mcp-starter/	Optional independent YouTube Worker.
server/	Browser module mirrors used by the local tests. Production source is under web-bridge-mcp/src/browser/.
tests/, extension-checks.mjs, web-bridge-checks.mjs	Regression suites.
docs/assets/	Project banner and a non-personal fixture capture.

Limits

• Your PC and Chrome must be running for browser control. The independent cloud-only tools do not require the PC. Mobile ChatGPT control has not been validated.
• Sessions last two hours. The pairing token lasts thirty days and is stored locally, not in Chrome Sync.
• An idle controlled tab is detached and its favicon restored after about two minutes. External debugger detachment may leave the marker until its 125-second expiry; browser favicon caching and site policy can affect rendering.
• Browser Pilot does not activate tabs or windows itself. A website's own JavaScript can still open and activate a popup. Simple new-context links are opened explicitly in the background; their JavaScript click handlers are not executed.
• Sensitive-action recognition is heuristic. An authorization to fill a field is not an authorization to submit it.
• Frames can be read, but unsupported frame interactions are blocked. No arbitrary model-supplied JavaScript, desktop-app control, clipboard access or automatic local-file uploads.
• CDP commands have bounded waits. A timeout can occur after a partial effect: inspect the current state before retrying. Input is not automatically replayed.

Credits

Browser Pilot extends DavidSZD/web-bridge-mcp and includes DavidSZD/youtube-transcript-mcp-starter. Their source templates are included with attribution. See upstream notes.

This is an independent project, not an official OpenAI, Google or Cloudflare product.