Browser Navigator MCP
This server provides full programmatic control of a Brave/Chrome browser through MCP, enabling AI assistants to automate web interactions, inspect pages, manage tabs/windows, capture data, and perform advanced tasks.
Browser navigation & history: Go to URLs, back/forward, wait for page load, and manage navigation state.
Element interaction: Click, type, hover, scroll, focus, and send keyboard keys using CSS selectors, visible text, or reference IDs.
DOM discovery & inspection: List interactive elements, inspect DOM structure, read accessibility tree, and get page info/content.
Complex UI handling: Tools like
focus_element,press_key, andscopehelp operate dialogs, modals, dropdowns, and custom widgets.Screenshots & PDF export: Capture page/element screenshots and save pages as PDFs.
Custom JavaScript execution: Run arbitrary JS (with confirmation) and inject persistent scripts.
Network control: Start/stop HTTP traffic capture, list requests, and send custom requests through the browser profile.
Tabs & windows management: List, open, switch, close, and inspect tabs and windows.
Search: Web search across 9 platforms and semantic search across open tabs (TF-IDF).
CAPTCHA detection & waiting: Detect challenges and pause automation until human solves.
Session & data persistence: Manage cookies (encrypted), bookmarks, and search recorded history.
Video control: Play, pause, seek, change volume/speed, and toggle fullscreen on HTML5 video/audio.
Health monitoring: Check server/connection status, window/tab counts, and store sizes.
Automates the Brave browser itself through CDP, providing navigation, clicking, typing, tab/window management, screenshots, PDF export, cookies, and video playback, and also supports Brave as a search platform.
Allows searching DuckDuckGo through the browser search tool.
Allows searching Facebook through the browser search tool.
Allows searching GitHub through the browser search tool and can interact with GitHub's web UI for complex widget automation.
Allows searching Google through the browser search tool.
Allows searching Instagram through the browser search tool.
Allows searching Perplexity through the browser search tool.
Allows searching Reddit through the browser search tool.
Allows searching Stack Overflow through the browser search tool.
Allows searching TikTok through the browser search tool.
Allows searching Wikipedia through the browser search tool.
Allows searching YouTube through the browser search tool.
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+debuggerInput)π Adaptive DOM tools β
list_elements,inspect_dom,focus_element,press_keydiscover 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) todata/screenshots/π§ Arbitrary JS β
execute_js(wrappedasync () => (code), requiresconfirm=true)π₯ Health check β server + extension transport state (
waiting/connected), window/tab countsπ§© UI β toolbar
popup.html(380px) + fulldashboard.html(overview/browser/tools/captures/settings/logs),manifest.jsonoptions_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 installQuick 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 to the browser extension (WebSocket already established by the extension); returns browser state |
| Reset the transport (windows/tabs stay open); next call re-handshakes automatically |
| Go to a URL (SSRF-guarded); |
| Back / forward; fast on bfcache pages |
| Click by CSS selector, visible text, or ref (ref_N from read_page); double-click & mouse buttons |
| Unified interaction: click/double-click/right-click/move/type/fill/key/scroll/hover/wait/navigate/screenshot by selector, text, coordinates, or ref |
| Type text; optional per-keystroke delay and Enter |
| Focus an element (needed for custom widgets like tag/chip inputs) |
| Send keys: Escape, Tab, Backspace, Arrow keys, combos, sequences |
| Scroll up/down/left/right (pixel amount) |
| Hover to reveal menus and tooltips |
| URL, title, load status, CAPTCHA presence |
| Extract visible text or raw HTML (10k char cap) |
| Accessibility tree with stable ref IDs (ref_1, ref_2...); filter interactive/all |
| List interactive elements with reusable CSS selectors |
| Inspect an element's structure, attributes, and children |
| PNG of the page or an element (saved under |
| Save the page as a PDF (saved under |
| Run arbitrary JS in the page (requires |
| Inject persistent content script (survives navigations, isolated world) |
| Send message to injected script and await reply |
| Wait until an element appears in the DOM |
| Wait for full page load |
| Start capturing HTTP requests via CDP (Fetch+Network) |
| Stop capture, return all requests as JSON |
| Peek at captured requests without stopping |
| Send custom HTTP request through browser (cookies apply) |
| Semantic search across ALL open tabs (TF-IDF cosine similarity) |
| List / open / switch / close tabs (background mode supported) |
| List / switch / close windows |
| Check CAPTCHA presence & solved status |
| Poll until the user solves a CAPTCHA |
| Play/pause/seek/volume/fullscreen on HTML5 video |
| Search 9 platforms: Google, Bing, DuckDuckGo, Brave, YouTube, Reddit, GitHub, Stack Overflow, Wikipedia |
| Local JSON bookmark store (tags, upsert by url) |
| Search server-recorded navigation history (time-filtered, persisted, capped 5000) |
| Get/set/export/import cookies (AES-256-GCM encrypted snapshots under |
| 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:
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.inspect_domβ understand how a widget is built: tag, attributes, classes, a CSS path, and child elements. Match by selector or exact visible text.focus_elementβ many widgets (e.g. GitHub tag/chip inputs) only accept keyboard input once focused. Focus the element, then:press_keyβ send keyboard input:Backspace/Deleteto remove a token chip,ArrowDown+Enterto pick a menu item,Escapeto dismiss a dialog,Tabto 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_jsrequiresconfirm=trueand is capped at 20000 chars.Screenshot & cookie paths are sanitized against path traversal.
Cookies are stored AES-256-GCM encrypted with
0o600permissions, directories with0o700.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
fetchpaths.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.cjsFive 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 toolsbookmark_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.
bookmark_searchC
Search bookmarks by keyword and/or tags
Inputs: tags, limit, query.
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.
history_searchB
Search recorded navigation history (most recent first)
Inputs: hours, limit, query.
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.
searchA
Run a web search in the active tab and return the top results
Inputs: query (required), limit, region, platform.
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
Scored across 41 tools
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.
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.
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.
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
Undetectable cloud browser sessions for AI agents and scrapers. Navigate, extract, click, captcha.
Cloud browser, web extraction, screenshots, and remote CDP tools for AI agents.
Control a real browser from AI agents: navigate, click, type, screenshot, read the page.
Stealth web automation for AI agents. Login, signup, navigate, screenshot.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceEnables 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
- FlicenseNot gradedqualityNot gradedmaintenanceEnables 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 npm1-
- AlicenseAqualityDmaintenanceEnables browser automation with anti-detection features, including navigation, interaction, form filling, and session management.2228 PyPI10MIT
- AlicenseNot gradedqualityDmaintenanceGives AI agents full control over Brave Browser, optimized for local LLMs to ensure low latency and high reliability.MIT