Skip to main content
Glama

Browser Navigator MCP

A Model Context Protocol server that gives AI assistants full control over Brave / Chrome via a Manifest V3 extension (no external browser download).

The extension (extension/background.js service worker + content.js DOM ops) bridges to the local MCP server over WebSocket ws://127.0.0.1:9224. The server speaks MCP over stdio and drives the real user profile β€” tabs, windows, clicks, typing, screenshots, PDFs, cookies, video β€” through chrome.tabs, chrome.windows, chrome.scripting and chrome.debugger.

Built so that an LLM can operate complex, dynamic UIs (dialogs, modals, dropdowns, token chips) without reverse-engineering the DOM: list_elements + inspect_dom + focus_element + press_key + scope.

Highlights

  • 🧭 Full browser control β€” navigate, back/forward, click, type, scroll, hover, keyboard input (extension cs.eval + debugger Input)

  • πŸ—‚ Adaptive DOM tools β€” list_elements, inspect_dom, focus_element, press_key discover how a UI is built and interact with it

  • πŸͺŸ Window & tab management β€” list, open, switch, and close windows and tabs (chrome.tabs/windows)

  • πŸ” CAPTCHA detection β€” detects reCAPTCHA, hCaptcha, Cloudflare Turnstile & challenges, pauses automation, and waits for a human

  • πŸͺ Session persistence β€” save/load cookies via chrome.cookies (encrypted), data/ JSON stores

  • πŸŽ₯ Video control β€” play/pause/seek/volume/mute on any HTML5 player

  • πŸ” Social search β€” search + search_tabs (TF‑IDF) across 9 platforms

  • πŸ“„ Export β€” screenshots (Page.captureScreenshot + captureVisibleTab) and PDF (Page.printToPDF) to data/screenshots/

  • πŸ”§ Arbitrary JS β€” execute_js (wrapped async () => (code), requires confirm=true)

  • πŸ₯ Health check β€” server + extension transport state (waiting/connected), window/tab counts

  • 🧩 UI β€” toolbar popup.html (380px) + full dashboard.html (overview/browser/tools/captures/settings/logs), manifest.json options_page β†’ dashboard

Related MCP server: Brave Real Browser MCP Server

Requirements

  • Node.js 20+

  • Brave / Chrome 118+ with extension loaded (see below)

  • No Playwright β€” extension does DOM/debugger work; server is ws + zod + @modelcontextprotocol/sdk

Installation

git clone https://github.com/ahmadhass0un/brave-browser-mcp.git
cd brave-browser-mcp
npm install

Quick Start

1. Load the extension

brave://extensions β†’ Developer mode β†’ Load unpacked β†’ select extension/. (A normal browser launch is enough β€” --remote-debugging-port is not required; the extension uses the in-browser chrome.debugger API, not the CDP port.) The toolbar shows Browser Navigator with popup (popup.html) and full dashboard (dashboard.html via chrome.runtime.getURL("dashboard.html")).

The extension probes http://127.0.0.1:9224/health every 2s and shows Waiting for MCP server… (yellow) until the server is up β€” the console stays silent in the meantime β€” then Connected.

2. Run the server (provides the WS counterpart)

npm install
node index.js              # stdio MCP + ws://127.0.0.1:9224
# or ./start.sh (optionally launches Brave via launch-brave.sh, then node)

The server speaks MCP over stdio. connect_brave wires the current tab (health shows connected:true) and navigate etc. go through the extension.

3. Register it as an MCP server

For opencode, add to opencode.json:

{
  "mcp": {
    "browser-navigator": {
      "type": "local",
      "command": ["node", "/absolute/path/to/brave-browser-mcp/index.js"],
      "enabled": true
    }
  }
}

For Claude Desktop, add to claude_desktop_config.json:

{
  "mcpServers": {
    "browser-navigator": {
      "command": "node",
      "args": ["/absolute/path/to/brave-browser-mcp/index.js"]
    }
  }
}

4. Start automating

connect_brave
navigate to https://example.com
list_elements on the page
click "Learn more"

Tools

All 43 tools (via tools.js β†’ bridge.js β†’ background.js ops):

Tool

Description

connect_brave

Connect to the browser extension (WebSocket already established by the extension); returns browser state

disconnect

Reset the transport (windows/tabs stay open); next call re-handshakes automatically

navigate

Go to a URL (SSRF-guarded); wait_for_captcha available when a challenge appears

navigate_history

Back / forward; fast on bfcache pages

click

Click by CSS selector, visible text, or ref (ref_N from read_page); double-click & mouse buttons

computer

Unified interaction: click/double-click/right-click/move/type/fill/key/scroll/hover/wait/navigate/screenshot by selector, text, coordinates, or ref

type

Type text; optional per-keystroke delay and Enter

focus_element

Focus an element (needed for custom widgets like tag/chip inputs)

press_key

Send keys: Escape, Tab, Backspace, Arrow keys, combos, sequences

scroll

Scroll up/down/left/right (pixel amount)

hover

Hover to reveal menus and tooltips

get_page_info

URL, title, load status, CAPTCHA presence

get_page_content

Extract visible text or raw HTML (10k char cap)

read_page

Accessibility tree with stable ref IDs (ref_1, ref_2...); filter interactive/all

list_elements

List interactive elements with reusable CSS selectors

inspect_dom

Inspect an element's structure, attributes, and children

screenshot

PNG of the page or an element (saved under screenshots/)

pdf_export

Save the page as a PDF (saved under screenshots/)

execute_js

Run arbitrary JS in the page (requires confirm=true)

inject_script

Inject persistent content script (survives navigations, isolated world)

send_to_injected

Send message to injected script and await reply

wait_for

Wait until an element appears in the DOM

wait_for_load

Wait for full page load

network_start

Start capturing HTTP requests via CDP (Fetch+Network)

network_stop

Stop capture, return all requests as JSON

network_list

Peek at captured requests without stopping

network_request

Send custom HTTP request through browser (cookies apply)

search_tabs

Semantic search across ALL open tabs (TF-IDF cosine similarity)

tabs

List / open / switch / close tabs (background mode supported)

windows

List / switch / close windows

detect_captcha

Check CAPTCHA presence & solved status

wait_for_captcha

Poll until the user solves a CAPTCHA

video_control

Play/pause/seek/volume/fullscreen on HTML5 video

search

Search 9 platforms: Google, Bing, DuckDuckGo, Brave, YouTube, Reddit, GitHub, Stack Overflow, Wikipedia

bookmark_add / bookmark_delete / bookmark_search / bookmark_list

Local JSON bookmark store (tags, upsert by url)

history_search

Search server-recorded navigation history (time-filtered, persisted, capped 5000)

cookies

Get/set/export/import cookies (AES-256-GCM encrypted snapshots under cookies/)

health

Server + connection status, open window/tab counts

Working with complex UIs

Dynamic pages β€” dialogs, modals, dropdowns, token chips, custom widgets β€” are hard to automate when you don't know the DOM. Instead of guessing selectors, use the discovery tools:

  1. list_elements β€” see what is actually clickable or typeable, with a reusable CSS selector for each element. Filter by kind (button, link, input, …), by text (contains), or scope to an open container.

  2. inspect_dom β€” understand how a widget is built: tag, attributes, classes, a CSS path, and child elements. Match by selector or exact visible text.

  3. focus_element β€” many widgets (e.g. GitHub tag/chip inputs) only accept keyboard input once focused. Focus the element, then:

  4. press_key β€” send keyboard input: Backspace/Delete to remove a token chip, ArrowDown+Enter to pick a menu item, Escape to dismiss a dialog, Tab to move between fields.

The scope parameter on click, type, focus_element, hover, inspect_dom, list_elements, and by_text targeting limits the search to a container β€” e.g. "[role=dialog]" for the currently open dialog β€” so you interact with the right element even when the page has many matches.

For example, removing a tag from GitHub's "Edit repository metadata" dialog:

focus_element(by_text="automation", scope="[role=dialog]")
press_key(key="Backspace")

CAPTCHA Handling

detect_captcha reports CAPTCHA presence (reCAPTCHA, hCaptcha, Cloudflare Turnstile, Cloudflare Challenge) and get_page_info includes a captcha field. wait_for_captcha blocks until a human solves the challenge in the browser β€” this tool cannot (and will not) bypass CAPTCHAs.

Security Notes

  • execute_js requires confirm=true and is capped at 20000 chars.

  • Screenshot & cookie paths are sanitized against path traversal.

  • Cookies are stored AES-256-GCM encrypted with 0o600 permissions, directories with 0o700.

  • The server never kills a browser it did not launch.

  • URL guards block loopback/private/metadata targets (SSRF) on navigate, tabs open, network_request, and fetch paths.

  • Signal handlers fail in-flight RPCs and close sockets on exit.

  • See AUDIT.md for the security & code-quality audit.

Testing

The suite drives the server over the real MCP stdio protocol (needs the extension loaded in a running Brave; no --remote-debugging-port required):

node test.cjs

Five smoke assertions (health, connect_brave, navigate, get_page_info, disconnect) run against the live extension bridge.

License

PolyForm Noncommercial 1.0.0 β€” see LICENSE.

Free to use for any noncommercial purpose. For commercial use, contact the author first.

Available Tools

41 tools
bookmark_addA

Add a bookmark (updates title/tags if the URL already exists)

Inputs: url (required), title (required), tags.

bookmark_deleteA

Delete a bookmark by id (or by exact URL)

Inputs: id, url.

bookmark_listA

List all saved bookmarks

Inputs: no named parameters.

clickA

Click an element by selector, visible text, or ref_N from read_page (trusted CDP click with DOM fallback)

Inputs: ref, scope, button, by_text, +3 more.

computerD

Unified interaction: click, double_click, right_click, move, type, fill, key, scroll, hover, wait, navigate, screenshot

Inputs: action (required), x, y, key, +9 more.

connect_braveB

Connect to the browser via the extension and report its state

Inputs: no named parameters.

cookiesA

Get cookies (filter by domain/name), set cookies, delete/clear (auto-backup first), export/import encrypted snapshots

Inputs: file, name, action, domain, +1 more.

detect_captchaB

Check whether the current page shows a CAPTCHA (recaptcha/hcaptcha/turnstile/geetest/funcaptcha)

Inputs: no named parameters.

disconnectA

Drop the connection to the browser (the browser itself keeps running)

Inputs: no named parameters.

execute_jsA

Run JavaScript in the page and return its result. Use return for a value; secrets in output are redacted unless redact=false. DANGER: requires confirm=true

Inputs: code (required), redact, tab_id, confirm.

focus_elementA

Move keyboard focus to an element (needed before press_key on custom widgets)

Inputs: scope, by_text, selector.

get_page_contentC

Extract readable text or raw HTML from the page or an element

Inputs: limit, format, selector.

get_page_infoC

Get the current page's URL, title, loading status, scroll state, interactivity, and CAPTCHA presence

Inputs: tab_id.

healthA

Server status, connection transport, store sizes, live refs, and uptime

Inputs: no named parameters.

hoverC

Hover over an element to reveal hover menus, tooltips, or submenus

Inputs: ref, scope, by_text, selector.

inject_scriptA

Register a named persistent script that replays on every navigation

Inputs: code (required), name (required), run_now.

inspect_domB

Inspect an element's tag, attributes, css path, subtree, and (optionally) HTML

Inputs: scope, by_text, selector, max_depth, +1 more.

list_elementsC

List elements of a kind (links, buttons, inputs...) with names and reusable selectors

Inputs: kind (required), limit, scope, contains.

network_listA

Peek at captured requests without stopping capture

Inputs: no named parameters.

network_requestC

Send an HTTP request through the browser profile (cookies/session apply)

Inputs: url (required), body, method, headers, +1 more.

network_startC

Start capturing HTTP traffic on the active tab via CDP

Inputs: max_time, include_static.

network_stopA

Stop network capture and return everything captured so far

Inputs: no named parameters.

pdf_exportA

Save the current page as PDF (A4, backgrounds on); saved under data/screenshots

Inputs: save_path.

press_keyC

Send keyboard keys ("Enter", "Control+a"); repeats the sequence times times

Inputs: key (required), times, selector.

read_pageA

Build an accessibility snapshot of the page with stable ref_N ids for click/type targeting

Inputs: filter, max_refs.

screenshotB

Capture a PNG of the page (full page) or one element; saved under data/screenshots

Inputs: selector, full_page, save_path.

scrollA

Scroll the page or an element (use down repeatedly for infinite scroll)

Inputs: amount, selector, direction.

search_tabsA

Search across all open tabs by title or URL (TF-IDF ranked)

Inputs: query (required), limit.

send_to_injectedA

Send JSON data to an injected script and await its reply

Inputs: name (required), data, timeout_ms.

tabsC

List, open, switch, close, or inspect tabs

Inputs: action (required), url, active, tab_id, +2 more.

typeB

Type text into an input/textarea/contenteditable (optionally char-by-char)

Inputs: text (required), ref, delay, scope, +2 more.

video_controlC

Control HTML5 video/audio playback: play, pause, toggle, mute, unmute, seek, set_speed, set_volume, fullscreen, exit_fullscreen, get_info

Inputs: action (required), value.

wait_forB

Poll the DOM until a CSS selector or visible text appears (or timeout)

Inputs: ref, text, selector, timeout_ms, +1 more.

wait_for_captchaC

Wait up to timeout_ms for the user to solve the page's CAPTCHA

Inputs: timeout_ms.

wait_for_loadC

Wait for the page to reach a load state

Inputs: until, timeout_ms.

windowsA

List browser windows, focus one, or close one

Inputs: action, window_id.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    C2.7/5.0

    Scored across 41 tools

    Disambiguation2/5

    The 'computer' unified-interaction tool overlaps heavily with dedicated click, type, scroll, hover, navigate, screenshot, and wait tools, making it unclear which to call. Additionally, read_page, get_page_content, list_elements, and inspect_dom all expose page content/structure in different forms, so selection is not obvious.

    Naming Consistency2/5

    Names are a mix of single verbs (click, scroll, hover), verb_noun (get_page_info, inspect_dom), noun_verb (network_start, bookmark_add), and bare nouns (tabs, windows, cookies, health). While bookmark_* and network_* clusters are internally consistent, the overall set lacks a predictable naming convention.

    Tool Count2/5

    At 41 tools, the server is well over the typical well-scoped range, and the count is inflated by a 'computer' meta-tool that duplicates many purpose-specific tools. A consolidated set of 15-20 targeted actions would likely cover the same functionality with less redundancy.

    Completeness5/5

    The tool surface covers the full browser automation lifecycle: connect, navigate, interact, read, wait, capture, manage tabs/windows, handle CAPTCHAs, media, search, network, cookies, bookmarks, and history. No obvious dead ends or missing core operations for mainstream browser automation tasks.

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables browser automation and web scraping with multi-session management, supporting page navigation, element interaction, network request capture, and content extraction across multiple concurrent browser instances.
      MIT
    • F
      license
      Not graded
      quality
      Not graded
      maintenance
      Enables advanced browser automation using real Brave Browser with 49 tools for web scraping, content extraction, video downloads, CAPTCHA solving, and anti-detection features. Includes automatic Brave installation, built-in ad-blocking with uBlock Origin, and support for complex scenarios like bypassing Cloudflare protection.
      1,699 npm
      1
      -
    • A
      license
      A
      quality
      D
      maintenance
      Enables browser automation with anti-detection features, including navigation, interaction, form filling, and session management.
      22
      28 PyPI
      10
      MIT