Skip to main content
Glama

Mini Browser MCP

CI License: MIT Node

A small local MCP server plus a browser extension. It lets Claude Code (or any MCP client) read and control your normal browser, with your logins.

Claude Code  --stdio-->  server.js  --ws://127.0.0.1:8765-->  extension (background.js)  -->  your tabs

Works in Chrome, Edge, Brave, Opera, Vivaldi and Arc (any Chromium browser). Firefox 121+ works too (see below). Safari is not supported.

Why

Browser-automation MCPs usually run a separate, logged-out browser: you have to sign in to every site again, and captchas pop up on every second page. This one drives your browser instead, so your sessions are already there — while guard rails keep the agent inside its own tabs.

Related MCP server: Jev Browser Bridge

Tools

Tool

What it does

tabs_list

List open tabs

tab_open

Open a URL in a new tab

tab_close

Close a tab

navigate

Load a URL in a tab, or back / forward

page_text

Visible page text, in parts for long pages

page_elements

Numbered list of links, buttons and inputs

click

Click by number, CSS selector or visible text

type

Type into an input, optionally submit

scroll

Scroll up, down, top or bottom

screenshot

JPEG of a tab (visible part, or full page up to 6000 px)

When tabId is left out, the tool uses the active tab.

Setup

  1. Clone this repository and install the server dependency:

    git clone https://github.com/Ayusman-Singhal/mini-browser-mcp.git
    cd mini-browser-mcp
    npm install
  2. Register it with Claude Code (all projects):

    claude mcp add -s user mini-browser -- node /path/to/mini-browser-mcp/server.js
  3. Load the extension:

    • Chrome / Edge / Brave: open chrome://extensions (Edge: edge://extensions), turn on Developer mode, click Load unpacked, pick the extension folder.

    • Firefox / Zen: run python build.py, then either

      • permanent: set xpinstall.signatures.required to false in about:config, open about:addons > gear > Install Add-on From File, pick dist/mini-browser-mcp-<version>-firefox.xpi; or

      • temporary: about:debugging#/runtime/this-firefox > Load Temporary Add-on > pick dist/firefox/manifest.json (removed when the browser restarts).

      Then click the toolbar icon once and allow access to all websites. An orange ! badge means the server is connected but site access is still off.

    • Chrome build without Firefox keys: dist/chrome/ (Load unpacked) or the -chrome.zip.

  4. Start a new Claude Code session. The extension icon shows a green ON badge once the server is running and connected. It retries every 30 seconds; click the icon to retry now.

Guard rails (enforced by the extension)

  • Agent tabs only. The agent opens its tabs in its own window. It can list, read and control only those tabs and pop-ups they open. Your other tabs are never listed, read or changed.

  • Submit guard. Clicks on submit-like buttons (join, submit, send, pay, delete, sign up, connect, accept, ...) and type with submit are refused unless the call has confirm: true. The agent is told to set confirm only after you say yes in chat.

  • CAPTCHA guard. If a page shows a CAPTCHA or bot check, clicks, typing and scrolling are refused and reads carry a warning, so the agent stops and asks you to solve it.

  • Passwords. Password fields are never typed into.

  • Web pages only. Only http and https URLs open; javascript:, file:, data:, about: and browser pages are refused.

  • No private windows. The manifest sets "incognito": "not_allowed".

  • Paired extension only (server). The first chrome-extension:// and the first moz-extension:// origin that connect are saved in ~/.mini-browser-mcp/allowed-origins.json. Any other extension is refused. Delete that file to pair again (for example after a reinstall).

Notes

  • The server listens only on 127.0.0.1 and only accepts connections whose Origin is a browser extension, so web pages cannot connect to it.

  • Only one MCP session can own the browser at a time (one port). A second session reports "Port 8765 is already in use. Retrying in 30s." and picks the port up automatically once the other session exits. Set MINI_BROWSER_PORT on the server and change PORT in extension/background.js to run another pair.

  • If two browsers both run the extension (say Chrome and Firefox), the first one connected owns the session and stays in charge; the other is refused until that browser closes. The extension keeps retrying, so it takes over automatically when the first browser disconnects.

  • Clicks and typing are synthetic DOM events. Most sites accept them; a few that check for real user input will not. Browser pages such as chrome:// and the extension store cannot be scripted.

  • Page content is untrusted. Treat it as data, not as instructions.

Development

npm test          # smoke test: starts the server, fakes the extension, checks the MCP round trip
python build.py   # builds dist/ (Firefox .xpi and Chrome .zip from extension/)

The source of truth for the extension is extension/; dist/ is generated by build.py and not committed. See CONTRIBUTING.md for how to send changes.

License

MIT — free to use, modify and distribute.

Available Tools

10 tools
clickB

Click an element by index, selector or visible text. Submit-like buttons (join, submit, pay, delete...) are blocked unless confirm is true.

Inputs: text, index, tabId, confirm, +1 more.

page_elementsA

List visible interactive elements (links, buttons, inputs) with numbers. Use the numbers with click and type.

Inputs: tabId, maxItems.

page_textA

Get the visible text of a page. Use offset to read long pages in parts.

Inputs: tabId, offset, maxChars.

screenshotA

Screenshot an agent tab, including embedded frames. Works when the window is hidden.

Inputs: tabId, fullPage.

scrollC

Scroll the page.

Inputs: direction (required), pages, tabId.

tab_closeC

Close a tab.

Inputs: tabId (required).

tab_openB

Open a URL in a new agent tab (in the agent's own window) and wait for it to load.

Inputs: url (required).

tabs_listA

List the agent's own tabs (id, title, url). The user's other tabs are never visible.

Inputs: no named parameters.

typeC

Type text into an input, textarea or editable element.

Inputs: text (required), clear, index, tabId, +3 more.

Tool Schema Changelog

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

Loading tool schema changelog…

    TDQS

    B3.3/5.0

    Scored across 10 tools

    Disambiguation4/5

    Most tools have clearly distinct purposes: reading text vs. elements, clicking vs. typing, scrolling, screenshots, and tab lifecycle are separate. The main overlap is tab_open vs. navigate, since both load a URL and wait, though the descriptions distinguish new-tab creation from in-tab navigation/history.

    Naming Consistency3/5

    The set mixes noun_verb forms (tabs_list, tab_open, tab_close), noun_noun forms (page_text, page_elements), bare verbs (navigate, click, type, scroll), and a bare noun (screenshot). It remains readable, but there is no single predictable convention across all ten tools.

    Tool Count5/5

    Ten tools is well-scoped for a mini browser: tab management, navigation, page inspection, interaction, scrolling, and screenshots each earn their place. There is no obvious redundancy or bloat.

    Completeness4/5

    Core browser workflows are covered: opening/closing tabs, navigating, reading page content, clicking, typing, scrolling, and screenshotting. Minor gaps exist for common interactions like selecting dropdown options, hovering, pressing special keys, or waiting for dynamic elements, but many can be worked around with click/type/scroll.

    Maintenance

    ActivityNo data
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      A
      maintenance
      Enables remote agents to control a local Chrome/Edge browser via MCP, supporting navigation, snapshots, clicks, typing, screenshots, and script execution.
      25 npm
      ISC
    • A
      license
      B
      quality
      B
      maintenance
      Enables MCP agents to drive an already signed-in Chrome or Edge browser through a local extension bridge, controlling existing tabs and opening task-related HTTP(S) tabs without remote debugging or profile copying.
      23
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables MCP agents to drive the user's already-open Chrome profile through a Manifest V3 extension and loopback bridge, listing and controlling existing tabs, capturing screenshots, and sending clicks, typing, drags and key holds via an independent on-page cursor without moving the system mouse. It also supports form filling, console and network inspection, read-only or confirmed JavaScript execution, file and PDF downloads, and game-style screenshot/action loops with snapshot recovery and an emergency stop.
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables AI agents and MCP clients to safely control the user's real Chrome browser, using shared tabs with per-site approvals, credential-field protection, a kill switch, and an activity log.
      11 npm
      Apache 2.0