Local Browser MCP
Enables controlling an existing Brave browser through a local Chrome extension, providing tools to manage tabs, navigate, read page content, take screenshots, interact with elements, and execute JavaScript.
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
Local Browser MCP
An independent, local-only MCP server and Chrome extension for controlling your existing browser tabs. The control plane stays on the same computer and requires no account, hosted service, routing identifier, access token, or remote relay.
This directory is the complete project. Copy it anywhere; it does not import, link to, or execute files from its parent repository.
It preserves the live @vibebrowser/mcp@0.3.6 22-tool MCP contract exactly —
order, names, titles, descriptions, input schemas, defaults, and annotations —
so agents, prompts, and skills written against that contract work unchanged.
Two local convenience tools remain beyond that compatibility boundary.
How it works
MCP client ── stdio ──> Node.js server ── ws://127.0.0.1:<port> ──> Chrome extensionMCP is exposed only through the child process's standard input/output.
The extension bridge binds explicitly to IPv4 loopback.
The extension connects only to
ws://127.0.0.1:<port>— the port comes fromconfig.jsor, in an unlocked development build, the options page.Server and extension complete a fail-closed handshake (profile name and protocol version) before any tool traffic flows.
There is no remotely reachable server mode.
"Local-only" describes the control plane. Chrome can still visit websites at your request, so ordinary page navigation can naturally use the internet. The project itself makes no relay, account, analytics, update, or telemetry request.
Related MCP server: dsh_browser_bridge
Private Finance OAuth navigation
The existing owner-only credential.sock accepts QBO-NAVIGATE/1 <pageId>\n.
This is a deliberately narrow private transport, not a new public MCP tool.
Only the finance bridge consumes its sibling
cache/qbo-oauth-state/authorization-url file, after checking physical,
owner-only directories and a bounded regular, single-link, owner-only file.
Only Intuit Accounting OAuth with the approved HTTPS callback is accepted.
The caller must first obtain an existing page ID from the profile's MCP tools.
No arbitrary path or URL is accepted in the socket request. The URL file is
unlinked before dispatch through the existing profile-bound extension bridge.
Replies are only NAVIGATED\n or ERROR\n; navigation results and exception
messages are never returned. NAVIGATED confirms dispatch success, not OAuth
completion: inspect the resulting page and verify grants using the QBO connector.
After an uncertain result, inspect current state rather than replaying a consumed
file. The publisher must create a fresh OAuth flow for a new attempt.
Build with npm run build. Reconnect only the Finance stdio connector to load
server changes; preserve the visible browser, other profile connectors and the
shared gateway. node server/test/private-navigation.mjs tests the file consumer
and actual private-socket protocol with synthetic URLs, without launching a browser.
Requirements
Node.js 18 or newer
npm
Chrome, Chromium, Brave, or another Chromium browser supporting
chrome.debuggerAn MCP client that can launch a stdio server
For
npm testonly: a Chromium binary that honors--load-extension(see Testing)
Install
From this directory:
npm install
npm run build
npm test
npm run doctorThe first installation downloads normal npm build/runtime dependencies. Runtime browser control remains local after installation.
Load the extension
Open
chrome://extensions.Enable Developer mode.
Select Load unpacked.
Choose this project's
extensiondirectory (or a stamped profile directory fromdist/profiles/<name>/— see Fleet deployment).
Chrome displays a debugger-control banner while the extension is attached to a tab. This is expected because browser actions use Chrome's supported debugger API.
The base development extension is intentionally unlocked: its options page
(right-click the toolbar icon → Options) may override the default port/profile.
Packaged fleet copies are stamped with locked=true; stored overrides are
ignored and the options controls are disabled, so a deployed profile cannot be
retargeted. The toolbar popup shows the effective route and connection state.
Configure your MCP client
Replace /path/to/local-browser-mcp with the absolute path to this directory:
{
"mcpServers": {
"local-browser": {
"command": "node",
"args": [
"/path/to/local-browser-mcp/server/dist/cli.js",
"--require-extension",
"--extension-connect-timeout", "90000"
]
}
}
}For Codex CLI:
codex mcp add local-browser -- node /path/to/local-browser-mcp/server/dist/cli.js --require-extensionCLI flags:
Flag | Default | Meaning |
|
| Loopback port the bridge listens on |
|
| Vibe-compatible alias for |
| none | Expected extension profile; mismatches are rejected (close 4403) |
| off | Fail startup unless the full tool contract is published |
|
| How long |
| off | Verbose stderr logging |
An optional leading start subcommand is accepted. The port can also come from
BROWSER_MCP_EXTENSION_PORT, HERMES_VIBE_EXTENSION_PORT, or
VIBE_MCP_EXTENSION_PORT (in that precedence order), and the profile from
BROWSER_MCP_PROFILE.
With --require-extension, the server refuses to enter the "success with zero
tools" state: it waits up to the connect timeout for the extension to connect
and advertise the exact Vibe-compatible contract, then either serves MCP or exits 1
with a clear stderr diagnosis (no extension, wrong profile, or tool drift). If
the extension later disconnects, an equal-length grace timer runs before the
server exits rather than serving an empty tool list. Without the flag, startup
is tolerant: tools/list waits briefly and late tools are announced via
notifications/tools/list_changed.
Startup order does not matter. The extension retries its loopback connection with bounded exponential backoff; handshake rejections (wrong profile or protocol) are fatal and stop reconnection until reconfigured.
Hermes profile adapter
Hermes profiles that previously used profile-vibe-mcp need to preserve one
additional responsibility: that wrapper owns the dedicated browser lease. Use
scripts/hermes-profile-browser-mcp as the MCP command so Browser MCP replaces
the Vibe process without bypassing browser launch, renewal, or release:
mcp_servers:
vibe: # keep this key to preserve the mcp_vibe_* tool namespace
command: /path/to/browser-mcp/scripts/hermes-profile-browser-mcp
args: []
env:
BROWSER_MCP_ROOT: /path/to/browser-mcp
BROWSER_MCP_BROWSER_LAUNCHER: /path/to/.hermes/bin/default-browser-native
BROWSER_MCP_STATE_DIR: /path/to/.hermes/profiles/default/cache/browser-mcp
BROWSER_MCP_EXTENSION_PORT: "21122"
BROWSER_MCP_PROFILE: default
BROWSER_MCP_CONNECT_TIMEOUT_MS: "90000"
connect_timeout: 120.0The extension artifact must be stamped with the same profile and extension port. The old Vibe agent port is intentionally absent: Browser MCP speaks MCP directly over stdio and owns only the profile's loopback extension port.
For a staged cutover, install the locked artifact and activate the matching
Hermes command together. If the extension is loaded while no process owns its
locked port, Chrome may retain a handled WebSocket connection-refused record at
the constructor line; that is an inactive route, not a malformed WebSocket.
Run doctor on the artifact, then verify the adapter through an MCP
tools/list call before retiring the old profile route.
Browser tools
Every compatible tool also accepts optional pageStateFormat with value
markdown or accessibility_tree. When supplied, the result appends state
captured from the exact target page after the operation.
The 22 contract tools, in the advertised order:
Tool | Required params | Optional params | Notes |
|
|
| Exact page; URL navigation defaults to 45s readiness |
| — | — | Deterministic page-ID listing with active markers |
| — |
| Background by default; readiness defaults on |
|
|
| Focuses exact tab/window and establishes visibility |
|
| — | Refuses to close the final remaining page |
|
|
| Real pointer input; link may open a background tab |
|
| — | Native setter plus input/change events |
|
| — | Ordered array of |
|
| top-level fields or | Inline base64 only; no host filesystem path |
|
|
| Types into the previously focused control |
|
| — |
|
|
|
| Non-empty text array; resolves when any item appears |
|
|
| Glob ( |
| — |
| Document readiness plus DOM-mutation quiet window |
|
|
| Polls caller-supplied JavaScript until truthy |
|
|
| Function declaration; string arguments; promises awaited |
|
|
| Optional snapshot index focus, then key/chord delivery |
|
|
| Holds pointer over snapshot index |
|
|
| Selector, uid/index, or |
|
|
| Viewport emulation |
|
|
| Cost-aware JPEG (PNG at quality 90) image block |
| — |
| Markdown/accessibility/ARIA with stable uids |
Local extras beyond the established contract (kept from the prototype, clearly annotated in tools/list):
Tool | Required params | Optional params | Notes |
| — |
| Visible |
|
|
| Evaluates a bare JS expression |
The profile-local protected credential broker also advertises an optional
renderer-opaque fallback on press_key with keys="CMD+V": pass both
xRatio and yRatio as finite viewport ratios strictly between 0 and 1,
derived from the center of the exact field in a fresh Browser MCP screenshot.
It is mutually exclusive with index, requires a one-use broker-staged
credential, and keeps both the click and secret typing inside the browser
bridge. The server adds these two optional fields to the public MCP schema;
the extension's original Vibe wire contract remains unchanged. Coordinates on
ordinary keypresses are rejected. Indexed failures return fixed, secret-free
categories so a caller can repair the page, take a fresh snapshot and stage a
new transfer instead of mistaking target failure for rejected credentials.
Several agents can share one profile browser, so a staged secret can be bound
to the exact tab that will receive it. HERMES-CREDENTIAL/2 <tabId> <length>\n
followed by the value stages a one-use secret for that tab only, for at most
120 seconds; CLEAR/2 <tabId>\n clears it. A protected CMD+V takes its own
tab's value, then falls back to the untagged slot that the original
HERMES-CREDENTIAL/1 <length>\n frame fills, so a paste on one tab can never
receive or consume a secret staged for another. CLEAR\n clears only the
untagged slot, and SMS steps no longer clear tab-bound values. With
BROWSER_MCP_REQUIRE_TAB_BOUND_SECRETS=1 the broker refuses untagged frames.
SMS capture chords accept a server-only targetTabId: the captured code is
then pasted only on that provider page's tab.
Window mode for a browser several jobs share
Set BROWSER_MCP_PAGE_ISOLATION=window on the server when several jobs use
one browser at the same time. The wire contract stays Vibe 0.3.6; the server
sends options: {pageIsolation: "window"} with every call, and the extension
then:
opens every
new_pagein a window of its own (chrome.windows.create,focused: false), placed on the first free 32-pixel step down and right of the oldest window and ending where that window ends, so job windows stay on the screen and never cover each other completely;focusis ignored;makes
switch_to_pageactivate the page inside its own window without raising or focusing any window;turns on CDP focus emulation for each page it attaches to, so focus, blur and
document.hasFocus()behave as in the front window;shows each page's window id in
list_pages(Page 12 [ACTIVE]: "Title" [window 5] - https://…), and never reports the page state of whatever page happens to be active.
The server refuses take_snapshot, evaluate_script, wait_for_url,
wait_for_network_idle, wait_for_condition (and the local extras) when the
call names no page, because the active page usually belongs to another job.
An extension that does not advertise the page-isolation-window capability in
its hello cannot run new_page or switch_to_page in this mode: the server
refuses them with "reload the extension" instead of silently sharing tabs.
Pages stay live behind other windows only when Chrome runs with
--disable-backgrounding-occluded-windows; minimized windows and background
tabs are still hidden. Leave the variable unset for the default behaviour.
The uid workflow
Call take_snapshot before interacting with elements. It returns compact
references such as @e12; pass those as uid to click/fill/upload, or as the
numeric index where the Vibe schema uses an index. Drag accepts a uid/index,
CSS selector, or coordinates. Uids are valid only for the latest snapshot
of that tab — taking a new snapshot renumbers them, and navigation invalidates
them. If a uid goes stale the tool fails closed with
Element @eN is stale; call take_snapshot again (after attempting exactly one
relocation by role and accessible name).
Readiness vs. waiting
Navigation-flavored tools establish bounded readiness: new_page and
navigate_page use 45 seconds by default, while switch_to_page uses 15.
The extension polls tab status until the page completes loading. On timeout it
succeed, appending the warning suffix
(page did not reach readyState=complete within Ns; it may still be loading).
The wait_for* tools hard-error on timeout with Timed out after Nms waiting for …. Defaults match Vibe: 10 seconds for text/DOM quiet and 15
seconds for URL/condition. Long waits are kept alive end-to-end by progress
frames that extend the server-side call timer.
Reliability
Each tool call has an end-to-end request ID and a per-tool bounded timeout (wait tools get their requested timeout plus margin).
Pending calls are replayed if the extension replaces its socket.
The extension caches completed responses and deduplicates replayed calls (at-most-once execution).
Stale socket-close events cannot invalidate a newer connection, and a rejected handshake never displaces an established one.
Heartbeats detect half-open connections.
CDP sessions are reused and reacquired after transport failure.
Stale accessibility references are relocated once by role and accessible name.
Reconnection backs off from one to thirty seconds; a
chrome.alarmskicker survives service-worker suspension.Chrome refuses the debugger on a tab that holds another extension's frame. When a 1Password panel (a passkey offer, save-login prompt or suggestion list) blocks a tab, the extension removes that panel from the page and retries, at most three times in about 1.5 s, and the next
take_snapshotof the tab says so once. It changes no setting and never reads the panel's frame. It leaves the panel open on Google's passkey and security-key challenge pages, where the prompt is the sign-in step itself, and never removes another extension's frame; there, and when the panel keeps coming back, the tool fails with Chrome'sCannot access a chrome-extension:// URL of different extensiontext plus what to do next (finish or close the panel outside the page tools, then take a new snapshot).When a call asks for page state (
pageStateFormat) and only that snapshot fails, the call keeps its own result and addsPage state … is unavailable:with the reason, instead of failing an action that already happened.
See ARCHITECTURE.md for the full call lifecycle and handshake state machine.
Fleet deployment
Run many isolated browser instances on one machine by giving each Chrome profile its own extension copy (unique port + profile name) and each MCP server the matching flags.
Package stamped extensions
npm run package -- --profile alpha:19901 --profile beta:19902
# or from a JSON manifest: npm run package -- --profiles fleet.json
# tests and other isolated builds can use: --output-dir /tmp/browser-mcp-distThis produces, deterministically (byte-identical zips for identical sources — store method, fixed 1980 timestamps, sorted entries):
dist/local-browser-extension-<version>.zip(+.sha256) unstamped base
dist/profiles/<name>/ stamped unpacked dir
dist/local-browser-extension-<version>-<name>.zip(+.sha256) stamped zip
dist/artifacts.json versions, ports, content hashesThe deployment test packages into a private temporary output directory, so
running npm test cannot delete or replace the active dist/profiles/*
deployment artifacts.
A 12-instance fleet is one port per profile, e.g.:
Profile | Port | Profile | Port |
fleet-0 | 19900 | fleet-6 | 19906 |
fleet-1 | 19901 | fleet-7 | 19907 |
fleet-2 | 19902 | fleet-8 | 19908 |
fleet-3 | 19903 | fleet-9 | 19909 |
fleet-4 | 19904 | fleet-10 | 19910 |
fleet-5 | 19905 | fleet-11 | 19911 |
For each instance: load dist/profiles/<name>/ unpacked into that Chrome
profile, and launch the server with
--extension-port <port> --profile <name> --require-extension. The handshake
rejects cross-wired connections (an extension stamped fleet-1 connecting to
the fleet-0 server is closed with code 4403 and stops retrying), so a
misconfigured instance fails loudly instead of controlling the wrong browser.
The profile-isolation test in server/test/ proves 12 concurrent instances
stay independent.
Verify an installed copy
npm run doctor -- --extension-dir dist/profiles/alpha
# or any deployed copy of a stamped directoryDoctor hashes installed allowlisted files before parsing configuration and never imports or executes installed JavaScript. It reports whether the effective route is immutable; profile artifacts must be locked and match their packaged name/port metadata. Modified or stale installs fail closed.
Upgrade and rollback
Bump the version in all five places (root
package.json,server/package.json,extension/manifest.json,server/src/contract.ts, andpackage-lock.json) — the packager, doctor, and tests all refuse to run with mismatched versions.npm test && npm run package -- --profiles fleet.json.Replace each deployed directory with the new
dist/profiles/<name>/, then reload the extension inchrome://extensions(or restart Chrome).Verify each with
npm run doctor -- --extension-dir <deployed path>.Rollback is the same procedure with the previous version's artifacts; zips are deterministic, so the
.sha256sidecars identify exactly what is deployed anywhere.
Security model
The control socket accepts loopback connections only. Other processes running as the same local user could still attempt to connect; local-only does not mean mutually authenticated. The profile handshake is a deployment-correctness check, not an authentication boundary.
Profile matching is strict equality, including the unset case: a server with no
--profileaccepts only extensions with no stamped profile (null === null), and any mismatch fails closed.The extension requires powerful
debugger,tabs, and<all_urls>access to control arbitrary tabs. Review the small, unbundledextension/background.jsbefore installing it.The
scriptingpermission is used only to remove a blocking 1Password panel from a page, as described under Reliability. The injected function reads the page's own elements, never the other extension's frame or storage.evaluate_script,wait_for_condition, andevaluaterun caller-supplied JavaScript in the selected page. Remove their entries fromextension/tools.js+server/src/contract.tsand their switch cases if your threat model does not permit arbitrary page code.upload_fileaccepts owner-supplied inline base64 only. Its schema and executor reject arbitrary host filesystem paths.One server process owns each port. Configure one MCP host process per port/profile pair.
Testing
npm test # build + all eight suites (below)
npm run test:browser # just the real-browser suiteThe suite, in order:
contract-sync — both production copies deep-match the independent live Vibe 0.3.6 fixture (order, text, schemas, defaults, and annotations), with synchronized package/manifest/lockfile versions.
e2e — the real bridge against a scripted fake extension: handshake happy path, close codes 4400/4403/4426, progress-extends-timeout, replay across reconnects,
waitForContract.mcp-contract — launches the real stdio CLI using
start --portand proves its actual tools/list matches the live fixture.profile-isolation — 12 concurrent bridge+extension pairs stay fully isolated; a cross-wired profile is rejected without disturbing the others; 12 parallel calls route correctly.
local-only-audit — source-level regex audit that no relay, fetch, XHR, beacon, or non-loopback WebSocket code exists in any shipped file.
deployment — packages locked profile artifacts twice, proves identical hashes, and verifies the inert hash-first doctor path.
hermes-wrapper — proves the lease-aware adapter launches, records, and releases the dedicated browser; passes the exact locked port/profile to the stdio server; and rejects unsafe configuration.
browser-e2e — loads a stamped extension into a real headless Chromium and exercises the full 24-tool surface against local test pages, including readiness, uids, key chords, uploads, waits, and screenshots.
extension-window-mode and page-isolation cover window mode: the
extension's window, switching, page-list and focus-emulation code against a
fake chrome, and the real stdio server's refusals, old-extension check and
default-mode wire format. Run every suite except browser-e2e on fleet hosts,
where headless browsers are not allowed.
The browser suite is hard-required: npm test fails with a clear error if
no suitable Chrome binary is found. Note that branded Google Chrome 137+
ignores --load-extension, so the test prefers Chrome for Testing / Chromium
builds (Puppeteer and Playwright caches are auto-detected). Point CHROME_BIN
at a binary to override:
CHROME_BIN="$HOME/.cache/puppeteer/chrome/<ver>/chrome-mac-arm64/Google Chrome for Testing.app/Contents/MacOS/Google Chrome for Testing" npm testIf a macOS Chrome-for-Testing build ignores unpacked extensions in headless
mode, run the same real-browser suite with BROWSER_E2E_HEADED=1. The test
still uses a fresh isolated profile and the stamped loopback-only extension.
Manual smoke test
Load a stamped dir (e.g.
dist/profiles/alpha) in Chrome.node server/dist/cli.js --require-extension --profile alpha --extension-port 19901under your MCP client: tools/list shows 24 tools.Quit Chrome and start the server again: it exits 1 with a clear
--require-extension failederror instead of serving zero tools.
Project layout
extension/ Unbundled Manifest V3 Chrome extension
extension/tools.js The 24 tool definitions (pure data, Node-importable)
extension/config.js Development defaults or locked stamped fleet route
server/src/contract.ts Vibe-compatible production contract + validation
server/src/ TypeScript MCP server and loopback bridge
server/test/fixtures/ Independent captured Vibe 0.3.6 tools/list fixture
server/test/ Eight test suites (see Testing)
scripts/package-extension.mjs Deterministic zip packager + profile stamping
scripts/doctor.mjs Installation and deployment verification
scripts/hermes-profile-browser-mcp Lease-aware Hermes MCP command adapter
scripts/clean.mjs Removes generated outputCommands
npm run build # Compile the server
npm test # Build + all eight test suites (requires a Chromium binary)
npm run doctor # Check environment, versions, contract; --extension-dir verifies a deploy
npm run package # Deterministic extension zips; --profile name:port stamps copies
npm run clean # Remove server/dist and distTool failure diagnostics
Failed tool calls emit a browser_tool_failure JSON record to server stderr.
It includes the time, an allowlisted profile/tool name, and a fixed error category
(for example execution_context_lost or stale_element). Raw error messages,
arguments, page contents, URLs, identifiers and credentials are never logged.
These diagnostics do not retry actions or change the tool response.
License
Apache-2.0. See LICENSE. Legal attribution in the license is retained for provenance; it is not part of the product name or user-facing identity.
ServiceTitan SMS request freshness
Indexed protected SMS delivery focuses the exact snapshot node through the
existing indexed press_key operation with Home, which changes only caret
position. A coordinate click receipt is not evidence that the OTP field has
focus. The broker still requires the exact provider field, same origin,
visibility, editability, supported input type and an empty value before typing.
Assignment repeats these guards atomically, uses the input's native value setter
and dispatches input/change events privately. It does not depend on simulated
typing into an active OS window. Only a verified private population receipt
permits the subsequent verification submission.
It may repeat only fixed transient readiness observations twice, 100ms apart;
it never repeats focus, capture, SMS requests, typing or submission. Failures
return fixed categories, and private tool results and consumed codes are
scrubbed. No-index compatibility delivery retains its exact focused-field
checks. This recovery does not weaken MFA freshness or enable unbound paste.
For an expiring ServiceTitan SMS flow, prepare the profile-owned Google Voice page before requesting SMS. No-index CMD+SHIFT+B records a private baseline of visible ServiceTitan codes on that exact tab. Request SMS once, then use no-index CMD+SHIFT+S on the same tab. This capture considers all visible correlated candidates, including inbox previews, and accepts exactly one distinct code absent from the baseline within 120 seconds; stale, missing, wrong-tab, expired, and replayed baselines fail closed. It returns only a dedicated baseline or capture acknowledgment, distinct from ordinary keyboard receipts. Consume the protected code immediately with indexed CMD+V into the exact ServiceTitan MFA field and submit once. Baseline hashes stay in process memory and clear with the protected transfer. The legacy CMD+SHIFT+C provider-correlated capture remains available for existing callers; it does not establish request freshness.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
Hosted real Google Chrome MCP with per-user persistent state. Navigate, click, type, screenshot.
Browser MCP for logged-in tasks. Uses your Chrome — credentials stay local. Zero-token replay.
Unofficial Browserless MCP — wraps the Browserless headless-Chromium REST API (browserless.io)
Let AI agents observe and control Chrome tabs you explicitly share via Browse Bridge.
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceEnables MCP clients to control real Chrome tabs in existing profiles, supporting navigation, interaction, screenshots, and console/network inspection across multiple Chrome instances.-
- AlicenseNot gradedqualityCmaintenanceEnables MCP clients to control a local Chrome browser, including tabs, navigation, reading, clicking, typing, screenshots, and exclusive per-task control with user-stop capabilities.1MIT
- AlicenseNot gradedqualityBmaintenanceEnables MCP agents to control existing browser tabs, including reading pages, clicking, typing, keyboard input, scrolling, screenshots, JavaScript evaluation, and CDP commands while using the current logged-in session.MIT
- AlicenseNot gradedqualityBmaintenanceEnables MCP clients to read and control the Chrome tabs you are already logged into, using existing sessions and logins without a separate browser profile.1MIT