Skip to main content
Glama
Superior Browser MCP

Superior Browser MCP

Superior Browser MCP

Browser automation via MCP for Chrome and Firefox with enhanced AI features

npm version License

What is this?

An enhanced MCP (Model Context Protocol) server that surpasses Blueprint MCP with advanced features for AI-powered browser automation. Uses your real browser profile with all your logged-in sessions, cookies, and extensions intact.

Related MCP server: LAM-mcp Browser Automation Server

Why Superior?

Feature

Blueprint MCP

Superior Browser MCP

Visual Overlays

❌

✅ Numbered element badges

Element Classification

Basic

✅ Full AI categorization

Form Detection

Basic

✅ Smart field matching

Ad Detection

❌

✅ Auto-detect & block

Popup Handling

❌

✅ Cookie, modal, notification

Self-Healing Selectors

❌

✅ Fuzzy matching on failure

Storage Management

❌

✅ localStorage & sessionStorage

Accessibility Tree

Basic

✅ Full ARIA support

CAPTCHA Detection

❌

✅ Report & alert

Login Form Detection

❌

✅ Auto-detect credentials

Visual Diff

❌

✅ Page state comparison

Installation

1. Install the MCP Server

npm install -g @superior/browser-mcp

2. Install the Browser Extension

Chrome / Edge / Opera

  • Download from Releases

  • Load unpacked at chrome://extensions/

Firefox

  • Download from Releases

  • Load at about:debugging#/runtime/this-firefox

3. Configure your MCP client

Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "superior-browser": {
      "command": "npx",
      "args": ["@superior/browser-mcp@latest"]
    }
  }
}

Claude Code:

claude mcp add browser npx @superior/browser-mcp@latest

Quick Start

  1. Start your MCP client (Claude Desktop, Cursor, etc)

  2. Click the Superior Browser MCP extension icon in your browser

  3. The extension auto-connects to the MCP server

  4. Ask your AI assistant to browse!

Available Tools

Connection Management

  • enable - Activate browser automation

  • disable - Deactivate browser automation

  • status - Check connection status

Tab Management

  • browser_tabs - List, create, attach, or close tabs

Navigation

  • browser_navigate - Navigate to URL, back, forward, reload

Content & Inspection

  • browser_snapshot - Get accessible page content

  • browser_take_screenshot - Capture visual screenshot

  • browser_extract_content - Extract page as markdown

  • browser_console_messages - Get console logs

  • browser_network_requests - Monitor network

Interaction

  • browser_interact - Click, type, hover, wait, scroll

  • browser_fill_form - Fill multiple form fields

  • browser_press_key - Press keyboard keys

  • browser_drag - Drag and drop elements

Advanced (Blueprint Features)

  • browser_evaluate - Execute JavaScript

  • browser_handle_dialog - Handle dialogs

  • browser_window - Resize, minimize, maximize

  • browser_pdf_save - Save page as PDF

  • browser_performance_metrics - Get Web Vitals

  • browser_verify_text_visible - Verify text

  • browser_verify_element_visible - Verify element


🆕 NEW: Enhanced Features

Visual Overlays

// Get numbered overlays on all interactive elements
get_visual_map({ includeLabels: true })
// Returns: Screenshot with numbered badges + element map

Interactive Element Map

// Get clean JSON map of all interactive elements
get_interactive_map({ 
  filterType: 'button',  // or 'input', 'link', 'form', etc
  filterArea: 'header'    // or 'main', 'footer', 'sidebar'
})

Smart Element Click

// Click element by overlay number from visual map
click_by_overlay_id({ overlayId: 42 })
hover_by_overlay_id({ overlayId: 15 })

Element Classification

analyze_page({
  includeAds: true,      // Detect ad placements
  includePopups: true,   // Detect modals, cookie banners
  includeForms: true,    // Detailed form analysis
  includeNavigation: true,
  includeTables: true
})

Smart Form Filling

smart_fill_form({
  formData: {
    "email": "user@example.com",
    "password": "secret123",
    "name": "John Doe"
  },
  submitAfter: true      // Auto-submit after filling
})

Form Analysis

get_form_analysis({
  includeSuggestions: true  // Get suggested test values
})
manage_cookies({ action: 'get' })
manage_cookies({ action: 'set', cookies: [{ name: 'token', value: 'abc123' }] })
manage_cookies({ action: 'delete', name: 'token' })

manage_storage({ action: 'get', type: 'local' })
manage_storage({ action: 'set', type: 'session', key: 'preferences', value: JSON.stringify({ theme: 'dark' }) })

Popup & Ad Detection

detect_popups({ 
  autoClose: true,  // Auto-accept cookies
  types: ['cookie_banner', 'modal', 'notification']
})

detect_ads({ 
  includePositions: true,
  blockAds: true    // Hide detected ads
})

Smart Waiting

wait_for({
  selector: '#dynamic-content',
  visible: true,
  timeout: 10000
})

wait_for({
  text: 'Success message',
  timeout: 5000
})

wait_for({
  condition: 'document.querySelector(".loaded") !== null'
})

Self-Healing Selectors

self_heal_selector({
  failedSelector: '#submit-button',
  textHint: 'Submit',    // Fuzzy match on text
  roleHint: 'button'     // Match by role
})
// Returns: Suggestions for alternative selectors

Accessibility Tree

get_accessibility_tree({
  maxDepth: 10,
  filterRole: 'button'   // Filter by ARIA role
})

CAPTCHA Detection

detect_captcha()
// Returns: { captchaDetected: true/false, type: 'reCAPTCHA', etc }

Login Form Detection

detect_login_form()
// Returns: { loginFormsDetected: true, forms: [...] }

Smart Scrolling

scroll_page({ action: 'lazy_load' })  // Load all lazy content
scroll_page({ action: 'element', selector: '#footer' })
scroll_page({ action: 'bottom' })

How it works

┌─────────────────────────┐
│   AI Assistant          │
│   (Claude, GPT, etc)    │
└───────────┬─────────────┘
            │
            │ MCP Protocol
            ↓
┌─────────────────────────┐
│   MCP Client            │
│   (Claude Desktop, etc) │
└───────────┬─────────────┘
            │ stdio/JSON-RPC
            ↓
┌─────────────────────────┐
│   superior-browser-mcp │
│   (this package)       │
└───────────┬─────────────┘
            │ WebSocket (localhost:5555)
            ↓
┌─────────────────────────┐
│   Browser Extension     │
└───────────┬─────────────┘
            │
            │ Chrome/Firefox APIs
            ↓
┌─────────────────────────┐
│   Your Browser          │
│   (real profile)        │
└─────────────────────────┘

Development

# Clone the repository
git clone https://github.com/superior-browser-mcp/superior-browser-mcp.git
cd superior-browser-mcp

# Install dependencies
npm install

# Run in development
npm run dev

# Build Chrome extension
npm run build:chrome

Project Structure

superior-browser-mcp/
├── server/                     # MCP Server
│   ├── cli.js                  # Server entry point
│   └── src/
│       ├── statefulBackend.js  # All tool implementations
│       ├── extensionServer.js  # WebSocket server
│       └── unifiedBackend.js   # Tool dispatcher
├── extensions/                 # Browser Extensions
│   ├── chrome/                 # Chrome extension (MV3)
│   │   ├── manifest.json
│   │   ├── popup.html
│   │   └── src/
│   │       ├── background.js
│   │       ├── content-script.js
│   │       └── popup.js
│   └── firefox/                # Firefox extension (MV2)
├── docs/                       # Documentation
└── package.json

Configuration

Environment Variables

# Local WebSocket port (default: 5555)
MCP_PORT=5555

# Debug mode
DEBUG=true

Command Line Options

superior-browser-mcp --debug              # Enable verbose logging
superior-browser-mcp --port 8080          # Use custom port

Security

  • MCP server only accepts local connections by default (localhost:5555)

  • Extension requires explicit user action to connect

  • All browser actions go through the browser's permission system

License

Apache License 2.0

Copyright (c) 2025 Superior Browser MCP

Available Tools

42 tools
analyze_pageC

🆕 Auto-detect and classify page components: forms, navigation, ads, popups, modals, cookie banners, tables, etc.

Inputs: includeAds, includeForms, includePopups, includeTables, +1 more.

authD

Manage PRO authentication

Inputs: action (required).

browser_console_messagesB

Get browser console messages with filtering

Inputs: url, text, level, limit, +1 more.

browser_dragC

Drag element to another element

Inputs: toSelector (required), fromSelector (required).

browser_evaluateC

Execute JavaScript in page context

Inputs: function, expression.

browser_extract_contentB

Extract page content as clean markdown with smart content detection

Inputs: mode, offset, selector, max_lines.

browser_fill_formC

Fill multiple form fields at once with smart field matching

Inputs: fields (required).

browser_handle_dialogC

Handle alert/confirm/prompt dialogs

Inputs: accept (required), text.

browser_interactC

Perform one or more interactions: click, type, hover, scroll, drag, wait, file upload, and more

Inputs: actions (required), onError.

browser_list_extensionsA

List installed browser extensions

Inputs: no named parameters.

browser_navigateA

Navigate to URL, back, forward, or reload page

Inputs: action (required), url.

browser_network_requestsB

Monitor and replay network requests with JSONPath filtering

Inputs: action (required), limit, method, offset, +5 more.

browser_pdf_saveB

Save current page as PDF

Inputs: path.

browser_performance_metricsB

Get Web Vitals and performance metrics

Inputs: no named parameters.

browser_reload_extensionsB

Reload unpacked/development browser extensions

Inputs: extensionName.

browser_snapshotB

Get accessible DOM snapshot of the page (fast, text-based)

Inputs: no named parameters.

browser_tabsB

Manage browser tabs: list, create, attach, or close tabs

Inputs: action (required), url, index, stealth, +1 more.

browser_take_screenshotB

Capture screenshot with optional overlays, element highlighting, or partial capture

Inputs: path, type, padding, quality, +5 more.

browser_verify_element_visibleC

Verify element is visible on page (for testing)

Inputs: selector (required).

browser_verify_text_visibleC

Verify text is visible on page (for testing)

Inputs: text (required).

browser_windowB

Manage browser window: resize, minimize, maximize, close

Inputs: action (required), width, height.

click_by_overlay_idB

🆕 Click an element by its overlay ID from the visual map

Inputs: overlayId (required).

compare_pagesA

🆕 Visual diff between current page state and a previous screenshot or URL

Inputs: outputPath, previousUrl, previousPath, highlightChanges.

detect_adsC

🆕 Detect ad elements on the page with detailed information

Inputs: blockAds, includePositions.

detect_captchaA

🆕 Detect if a CAPTCHA or bot verification is present on the page

Inputs: no named parameters.

detect_login_formA

🆕 Auto-detect login forms and provide structured information about username/password fields

Inputs: no named parameters.

detect_popupsC

🆕 Detect and handle popups, modals, cookie banners, and notifications

Inputs: types, autoClose.

disableB

Deactivate browser automation and disconnect from browser extension

Inputs: no named parameters.

enableA

Activate browser automation. Required first step before any browser interaction.

Inputs: client_id (required), force_free.

get_accessibility_treeA

🆕 Get the full accessibility tree with ARIA roles, names, and states (screen reader view)

Inputs: maxDepth, filterRole, includeHidden.

get_element_detailsC

🆕 Get detailed information about specific elements including computed styles, accessibility info, and state

Inputs: selector, overlayId, includeStyles, includeAccessibility.

get_form_analysisA

🆕 Get detailed analysis of all forms on page including field types, labels, required status, and validation rules

Inputs: formSelector, includeSuggestions.

get_interactive_mapA

🆕 Get a clean JSON map of ALL interactive elements with IDs, types, labels, and positions. Perfect for AI understanding of page layout.

Inputs: filterArea, filterType, maxElements, includeHidden.

get_visual_mapA

🆕 Get visual map of interactive elements with numbered overlays. Shows a screenshot where every clickable element has a number badge. Use "click(42)" style references.

Inputs: path, type, quality, fullPage, +2 more.

hover_by_overlay_idA

🆕 Hover over an element by its overlay ID from the visual map

Inputs: overlayId (required).

manage_cookiesC

🆕 Get, set, or delete browser cookies

Inputs: action (required), name, domain, cookies.

manage_storageC

🆕 Access and modify localStorage and sessionStorage

Inputs: type (required), action (required), key, value.

scroll_pageC

🆕 Smart scroll with lazy loading support, can scroll to specific elements or areas

Inputs: action (required), x, y, loadAll, +1 more.

self_heal_selectorA

🆕 Find the best matching element when a selector fails, using fuzzy matching on text, role, and attributes

Inputs: failedSelector (required), roleHint, textHint.

smart_fill_formC

🆕 Auto-detect form fields and fill them intelligently based on field labels, names, and types

Inputs: formData (required), submitAfter, formSelector.

statusB

Check current connection status and browser state

Inputs: no named parameters.

wait_forC

🆕 Smart wait for elements, text, or conditions with retry

Inputs: text, timeout, visible, selector, +1 more.

Tool Schema Changelog

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

Loading tool schema changelog…

    TDQS

    C2.6/5.0

    Scored across 42 tools

    Disambiguation2/5

    Many tools have overlapping purposes, such as browser_interact vs click_by_overlay_id/hover_by_overlay_id, browser_fill_form vs smart_fill_form, and several detection tools (popups, ads, captcha, login). The visual/interactive map tools also overlap heavily. Agents will struggle to choose the right tool.

    Naming Consistency1/5

    Tool names mix snake_case (click_by_overlay_id, detect_popups) with camelCase (browser_navigate, browser_take_screenshot), and some use the 'browser_' prefix while others do not. There is no consistent verb_noun pattern, making the API feel chaotic.

    Tool Count2/5

    42 tools is excessive for a browser automation server, especially when many could be consolidated (e.g., unified interaction tool, unified form tool, unified detection tool). The high count with redundancy suggests the set is not well-scoped.

    Completeness4/5

    The server covers a wide range of browser automation needs: navigation, interaction, forms, screenshots, popups, ads, captchas, cookies, storage, network, console, performance, tabs, windows, dialogs, and extensions. Minor gaps exist (e.g., explicit element selection or file upload tool, though browser_interact covers them), but overall the surface is quite comprehensive.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers