Superior Browser MCP
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Superior Browser MCP fill the login form with email admin@test.com and password test123"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Superior Browser MCP
Browser automation via MCP for Chrome and Firefox with enhanced AI features
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-mcp2. 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@latestQuick Start
Start your MCP client (Claude Desktop, Cursor, etc)
Click the Superior Browser MCP extension icon in your browser
The extension auto-connects to the MCP server
Ask your AI assistant to browse!
Available Tools
Connection Management
enable- Activate browser automationdisable- Deactivate browser automationstatus- 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 contentbrowser_take_screenshot- Capture visual screenshotbrowser_extract_content- Extract page as markdownbrowser_console_messages- Get console logsbrowser_network_requests- Monitor network
Interaction
browser_interact- Click, type, hover, wait, scrollbrowser_fill_form- Fill multiple form fieldsbrowser_press_key- Press keyboard keysbrowser_drag- Drag and drop elements
Advanced (Blueprint Features)
browser_evaluate- Execute JavaScriptbrowser_handle_dialog- Handle dialogsbrowser_window- Resize, minimize, maximizebrowser_pdf_save- Save page as PDFbrowser_performance_metrics- Get Web Vitalsbrowser_verify_text_visible- Verify textbrowser_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 mapInteractive 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
})Cookie & Storage Management
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 selectorsAccessibility 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:chromeProject 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.jsonConfiguration
Environment Variables
# Local WebSocket port (default: 5555)
MCP_PORT=5555
# Debug mode
DEBUG=trueCommand Line Options
superior-browser-mcp --debug # Enable verbose logging
superior-browser-mcp --port 8080 # Use custom portSecurity
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 toolsanalyze_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_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
Scored across 42 tools
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.
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.
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.
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
Related MCP Connectors
AI-powered browser automation — navigate, click, fill forms, and extract data from any website.
Browser agents and stealth cloud browsers for AI: run web tasks, fill forms, extract data.
AI-powered web automation. Navigate websites using AI agents for one page or a thousand
AI-powered web automation. Navigate websites using AI agents for one page or a thousand
Related MCP Servers
- AlicenseAqualityDmaintenanceEnables browser automation with anti-detection features, including navigation, interaction, form filling, and session management.2228 PyPI10MIT
- AlicenseNot gradedqualityDmaintenanceEnables AI assistants to perform intelligent browser automation with session-based context analysis, including navigation, form filling, and content extraction through natural language.MIT
- AlicenseAqualityCmaintenanceEnables AI agents to fully control a browser for web automation, including navigation, clicking, typing, scrolling, screenshots, and DOM inspection, with session persistence and anti-bot bypass.4036 npmMIT
- AlicenseAqualityDmaintenanceAutomate your browser with AI using your existing profile, enabling logged-in sessions and stealth automation.12Apache 2.0