Browser MCP Server

A universal browser automation MCP server using Playwright. Control Chrome programmatically through the Model Context Protocol.

63 powerful browser automation tools including multi-tab management, media monitoring/control, low-level interaction, session recording, CDP-based performance profiling, network analysis, security testing, and on-demand documentation.

Features

• ✅ Smart Chrome Detection: Automatically finds and uses system Chrome/Chromium

• ✅ Three-Tier Strategy: Antigravity Chrome → System Chrome → Playwright Chromium

• ✅ Universal: Works with Antigravity, Claude Desktop, and any MCP client

• ✅ 63 Tools: Media control, multi-tab, pixel-based interaction, CDP power user tools, and more

• ✅ On-Demand Docs: Built-in documentation tool with return schemas and examples

• ✅ Auto-Install: Playwright installed automatically via npm (no manual setup)

• ✅ Safe: Isolated browser profile (won't touch your personal Chrome)

• ✅ Console Capture: Debug JavaScript errors in real-time

• ✅ Session Recording: Playwright traces with screenshots, DOM, and network activity

• ✅ Auto-Reconnect: Handles browser crashes gracefully

Quick Reference

Key Points:

• ✅ Requires Node.js >= 16.0.0

• ✅ Playwright installs automatically (via npm) or manually (via git clone)

• ✅ Automatically detects and uses system Chrome/Chromium

• ✅ Uses absolute paths in config files

• ✅ Isolated browser profile (won't touch personal Chrome)

• ✅ Restart MCP client after config changes

Quick Start

Installation

Method 1: NPM Package (Recommended)

# Install globally (Playwright installs automatically)
npm install -g @ricardodeazambuja/browser-mcp-server

# Or use directly with npx (no installation needed)
npx @ricardodeazambuja/browser-mcp-server

Note: Playwright is installed automatically as a dependency. The server will automatically detect and use your system Chrome/Chromium if available, or fall back to Playwright's Chromium.

Method 2: Clone Repository (For Development)

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

# Install dependencies (includes Playwright)
npm install

# Optional: Install Chromium browser if not using system Chrome
npx playwright install chromium

Method 3: Direct Download (Single File)

# Download the main file directly (no git required)
curl -o src/index.js \
  https://raw.githubusercontent.com/ricardodeazambuja/browser-mcp-server/main/src/index.js

# Install Playwright
npm install playwright

# Optional: Install Chromium browser if not using system Chrome
npx playwright install chromium

Usage with Claude Desktop

Add to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

Using local installation:

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

Using NPM:

{
  "mcpServers": {
    "browser-tools": {
      "command": "npx",
      "args": ["-y", "@ricardodeazambuja/browser-mcp-server"]
    }
  }
}

Note: Replace /absolute/path/to/ with the actual path where you installed the file.

Usage with Antigravity

Add to ~/.gemini/antigravity/mcp_config.json:

Using local installation:

{
  "mcpServers": {
    "browser-tools": {
      "command": "node",
      "args": ["/home/username/.gemini/antigravity/src/index.js"]
    }
  }
}

Using NPM:

{
  "mcpServers": {
    "browser-tools": {
      "command": "npx",
      "args": ["-y", "@ricardodeazambuja/browser-mcp-server"]
    }
  }
}

Then refresh MCP servers in Antigravity.

Usage with Claude Code

Add the browser-mcp-server using the Claude CLI:

Using local installation:

# Install the MCP server with default isolated profile
claude mcp add --transport stdio browser \
  -- node /absolute/path/to/src/index.js

# Or with custom browser profile for more control
claude mcp add --transport stdio browser \
  --env MCP_BROWSER_PROFILE=/path/to/custom/profile \
  -- node /absolute/path/to/src/index.js

Using NPM:

# Install using npx (no local installation needed)
claude mcp add --transport stdio browser \
  -- npx -y @ricardodeazambuja/browser-mcp-server

# With custom browser profile
claude mcp add --transport stdio browser \
  --env MCP_BROWSER_PROFILE=/path/to/custom/profile \
  -- npx -y @ricardodeazambuja/browser-mcp-server

Verify installation:

# List all MCP servers
claude mcp list

# Check server status
claude mcp get browser

Example usage in Claude Code:

# Natural language commands
> Navigate to https://example.com and take a screenshot
> Click the login button and fill in the username field
> What's the text in the .main-content selector?

# Direct tool invocation via slash commands
> /mcp__browser__browser_navigate https://example.com
> /mcp__browser__browser_screenshot

Note: The server uses an isolated browser profile at /tmp/chrome-mcp-profile by default, ensuring it won't access your personal Chrome cookies or data.

Usage with Gemini CLI

Add the browser-mcp-server using the Gemini CLI commands:

Using local installation:

# Install the MCP server with default isolated profile
gemini mcp add browser node /absolute/path/to/src/index.js

# Or with custom browser profile
gemini mcp add -e MCP_BROWSER_PROFILE=/path/to/custom/profile browser \
  node /absolute/path/to/src/index.js

Using NPM:

# Install using npx (no local installation needed)
gemini mcp add browser npx -y @ricardodeazambuja/browser-mcp-server

# With custom browser profile
gemini mcp add -e MCP_BROWSER_PROFILE=/path/to/custom/profile browser \
  npx -y @ricardodeazambuja/browser-mcp-server

Management commands:

# List all configured MCP servers
gemini mcp list

# Remove the server if needed
gemini mcp remove browser

Example usage in Gemini CLI:

# Natural language commands
> Navigate to https://github.com and take a screenshot
> Click the search button and type "MCP servers"
> Get the text from the .repository-content selector

# The CLI will use the browser automation tools automatically

Advanced options:

# Add with specific scope (user vs project)
gemini mcp add -s user browser node /path/to/src/index.js

# Add with timeout configuration
gemini mcp add --timeout 30000 browser node /path/to/src/index.js

# Skip tool confirmation prompts (use with caution)
gemini mcp add --trust browser node /path/to/src/index.js

Available Tools (63)

Documentation

1. browser_docs(toolName?) - Get detailed docs, return schemas, examples, and caveats for any tool

Multi-Page Management

2. browser_list_pages() - List all open tabs/pages

3. browser_new_page(url?) - Open a new tab

4. browser_switch_page(index) - Switch active tab

5. browser_close_page(index?) - Close a tab

Media Awareness & Control

6. browser_get_media_summary() - List all audio/video elements with state

7. browser_get_audio_analysis(durationMs?, selector?) - Analyze audio output (volume, spectrum)

8. browser_control_media(selector, action, value?) - Play, pause, mute, seek

Navigation & Interaction

9. browser_navigate(url) - Navigate to a URL

10. browser_click(selector) - Click an element (selector-based)

11. browser_type(selector, text) - Type text into an input

12. browser_scroll(x?, y?) - Scroll the page (generic)

13. browser_reload() - Reload current page

14. browser_go_back() - Navigate back

15. browser_go_forward() - Navigate forward

16. browser_wait(ms) - Pause execution

Low-Level Interaction

17. browser_mouse_move(x, y) - Move mouse to pixel coordinates

18. browser_mouse_click(x?, y?, button?, count?) - Click at pixel coordinates

19. browser_mouse_drag(fromX, fromY, toX, toY) - Drag and drop

20. browser_mouse_wheel(deltaX, deltaY) - Scroll mouse wheel

21. browser_press_key(key) - Send keyboard event (e.g. "Enter")

Information Gathering

22. browser_screenshot(fullPage?) - Capture screenshot

23. browser_get_text(selector) - Get text from element

24. browser_get_dom(selector?) - Get DOM structure

25. browser_read_page() - Get page metadata (title, URL)

26. browser_evaluate(code) - Execute JavaScript

Console Debugging

27. browser_console_start(level?) - Start capturing logs

28. browser_console_get(filter?) - Get captured logs

29. browser_console_clear() - Clear logs and stop

Advanced Interaction

30. browser_hover(selector) - Hover over element

31. browser_focus(selector) - Focus element

32. browser_select(selector, values) - Select dropdown options

33. browser_wait_for_selector(selector, timeout?) - Wait for element

34. browser_resize_window(width, height) - Resize window

35. browser_start_video_recording(path?) - Start session recording

36. browser_stop_video_recording() - Stop and save recording

37. browser_health_check() - Verify browser connection

🔬 Power User Tools (CDP-Based)

Advanced diagnostic tools using Chrome DevTools Protocol for performance analysis, network debugging, security testing, and storage inspection. These 26 additional tools provide deep insights into browser internals.

Performance Profiling (8 tools)

38. browser_perf_start_profile(sampleInterval?) - Start CPU profiling

39. browser_perf_stop_profile() - Get CPU profile data with summary

40. browser_perf_take_heap_snapshot(reportProgress?) - Capture memory snapshot

41. browser_perf_get_heap_usage() - Current JavaScript heap statistics

42. browser_perf_get_metrics() - Runtime metrics (DOM nodes, listeners, etc.)

43. browser_perf_get_performance_metrics() - Web vitals (FCP, LCP, CLS, TTFB)

44. browser_perf_start_coverage(resetOnNavigation?) - Track code coverage

45. browser_perf_stop_coverage() - Get coverage results

Use Cases: Memory leak detection, CPU profiling, performance optimization, code coverage analysis, web vitals monitoring

Network Analysis (7 tools)

46. browser_net_start_monitoring(patterns?) - Monitor network requests

47. browser_net_get_requests(filter?) - Get captured requests with timing

48. browser_net_stop_monitoring() - Stop monitoring and clear log

49. browser_net_export_har(includeContent?) - Export HTTP Archive log

50. browser_net_get_websocket_frames(requestId) - Inspect WebSocket frames

51. browser_net_set_request_blocking(patterns) - Block URL patterns

52. browser_net_emulate_conditions(offline, latency, download, upload) - Network throttling

Use Cases: API debugging, HAR export, WebSocket debugging, performance testing, request blocking, network throttling

Security Testing (6 tools)

53. browser_sec_get_security_headers() - Inspect security HTTP headers

54. browser_sec_get_certificate_info() - TLS/SSL certificate details

55. browser_sec_detect_mixed_content() - Find HTTP resources on HTTPS pages

56. browser_sec_start_csp_monitoring() - Monitor CSP violations

57. browser_sec_get_csp_violations() - Get violation log

58. browser_sec_stop_csp_monitoring() - Stop monitoring

Use Cases: Security audits, CSP debugging, HTTPS migration, certificate validation, mixed content detection

Storage & Service Workers (5 tools)

59. browser_storage_get_indexeddb(databaseName?, objectStoreName?) - Inspect IndexedDB

60. browser_storage_get_cache_storage(cacheName?) - List Cache Storage entries

61. browser_storage_delete_cache(cacheName) - Delete cache

62. browser_storage_get_service_workers() - Service worker state

63. browser_storage_unregister_service_worker(scopeURL) - Unregister worker

Use Cases: IndexedDB inspection, Cache Storage management, Service Worker debugging, offline functionality testing

Getting Started with CDP Tools

// Start CPU profiling
browser_perf_start_profile({})
// ... perform actions to profile ...
browser_perf_stop_profile({})  // Get results

// Monitor network activity
browser_net_start_monitoring({})
// ... navigate and interact ...
browser_net_get_requests({ filter: 'api' })
browser_net_export_har({})

// Security audit
browser_sec_get_security_headers({})
browser_sec_start_csp_monitoring({})
// ... trigger violations ...
browser_sec_get_csp_violations({})

// Inspect storage
browser_storage_get_indexeddb({ databaseName: 'myDB' })
browser_storage_get_cache_storage({ cacheName: 'my-cache-v1' })

Note: All CDP tools have comprehensive documentation available via browser_docs({ toolName: 'browser_perf_start_profile' }).

On-Demand Documentation

The browser_docs tool provides comprehensive documentation for all browser tools without increasing token overhead in normal operations.

Why This Matters

• Token Efficient: Tool descriptions stay concise (saving tokens on every request)

• Comprehensive: Detailed docs available when needed (return schemas, examples, caveats)

• Self-Documenting: AI agents can discover tool capabilities on-demand

What You Get

When calling browser_docs(toolName), you receive:

• Parameter Details: Types, optionality, defaults, enums

• Return Value Schemas: Exact structure of what the tool returns

• Selector Syntax: How to write Playwright selectors (CSS, text, data attributes)

• Important Caveats: Warnings about CORS, clearing behavior, state management

• Practical Examples: Real-world usage patterns

Usage

// Get docs for a specific tool
browser_docs({ toolName: 'browser_get_audio_analysis' })

// List all available tools
browser_docs({})

// Invalid tool name suggests similar tools
browser_docs({ toolName: 'navigate' })
// → Did you mean: browser_navigate, browser_go_back, ...

Example Output

📖 browser_type(selector, text)

Type text into an input field.

Parameters:
  • selector (string, required) - Playwright selector for the input
  • text (string, required) - Text to type

Returns:
  { content: [{ type: 'text', text: 'Typed into <selector>' }] }

⚠️ Important:
  • Uses page.fill() which CLEARS the field first, then types
  • Does NOT append to existing text

Example:
  browser_type({ selector: '#username', text: 'john@example.com' })

Examples

Navigate and Screenshot

// Agent uses:
browser_navigate("https://example.com")
browser_screenshot(fullPage: true)

Debug JavaScript Errors

// Agent uses:
browser_console_start()
browser_navigate("https://myapp.com")
browser_click("#submit-button")
browser_console_get(filter: "error")
// Shows: ❌ [ERROR] Uncaught TypeError: ...

Media Monitoring & Control

// Agent uses:
browser_navigate("https://youtube.com/watch?v=...")
browser_get_media_summary() // See active video state
browser_control_media(selector: "video", action: "play")
browser_get_audio_analysis(durationMs: 2000) // "Hear" the volume

Multi-Tab Automation

// Agent uses:
browser_navigate("https://wikipedia.org")
browser_new_page("https://google.com")
browser_list_pages() // Shows 2 pages
browser_switch_page(0) // Back to Wikipedia

Pixel-Based Interaction

// Agent uses:
browser_mouse_move(500, 300)
browser_mouse_click(button: "right")
browser_press_key("Enter")

Get Tool Documentation

// Agent uses:
browser_docs(toolName: "browser_get_audio_analysis")
// Returns:
// 📖 browser_get_audio_analysis(durationMs?, selector?)
//
// Parameters:
//   • durationMs (number, optional) - Duration to analyze in ms (default: 2000)
//   • selector (string, optional) - Selector for specific media element
//
// Returns: { isSilent: boolean, averageVolume: number, ... }
// ⚠️ Important: Requires CORS headers for cross-origin media

// List all tools:
browser_docs()  // Shows all 63 tools

How It Works

Three-Tier Browser Strategy (Automatic)

The server automatically chooses the best browser option:

Tier 1 - Antigravity Mode:

• Detects Chrome on port 9222

• Connects to existing Antigravity browser

• Uses Antigravity's browser profile

• No new browser window

Tier 2 - System Chrome/Chromium:

• Searches common locations: /usr/bin/google-chrome, /usr/bin/chromium, etc.

• Uses system-installed Chrome if found

• Saves ~275MB (no Chromium download needed)

• Uses isolated profile (/tmp/chrome-mcp-profile)

Tier 3 - Playwright Chromium:

• Falls back to Playwright's bundled Chromium

• Requires: npx playwright install chromium

• Uses isolated profile (/tmp/chrome-mcp-profile)

• New browser window appears

Safety Features

• Isolated Profile: Uses /tmp/chrome-mcp-profile (not your personal Chrome!)

• No Setup Dialogs: Silent startup with --no-first-run flags

• Clean Environment: No extensions, sync, or background updates

• Reproducible: Same behavior across systems

Security

This MCP server provides powerful browser automation capabilities. Please review these security considerations:

Isolated Browser Profile

• Uses /tmp/chrome-mcp-profile by default (configurable via MCP_BROWSER_PROFILE)

• Does NOT access your personal Chrome data (cookies, passwords, history)

• Each instance runs in a clean, isolated environment

Tool Safety

browser_evaluate: Executes arbitrary JavaScript in the browser context

• Code runs in browser sandbox (no access to your host system)

• Only executes when explicitly called by MCP client

• Requires user approval in most MCP clients

• Recommendation: Only use with trusted MCP clients and review code when possible

browser_navigate: Navigates to any URL

• Can visit any website the browser can access

• Uses isolated profile to prevent cookie/session theft

• Recommendation: Be cautious with URLs from untrusted sources

Debug Logs

• Server logs to /tmp/mcp-browser-server.log

• Logs may contain visited URLs and error messages

• Log file is cleared on system reboot (stored in /tmp)

• Does NOT log page content or sensitive data

Best Practices

• ✅ Only use with trusted MCP clients (Claude Desktop, Antigravity, etc.)

• ✅ Review automation scripts before execution when possible

• ✅ Use the default isolated profile (don't point to your personal Chrome)

• ✅ Report security issues via GitHub Issues

Configuration

Environment Variables

# Custom browser profile location (optional)
export MCP_BROWSER_PROFILE="$HOME/.mcp-browser-profile"

# Then run the server
node src/index.js

MCP Config with Environment Variables

{
  "mcpServers": {
    "browser-tools": {
      "command": "node",
      "args": ["/path/to/src/index.js"],
      "env": {
        "MCP_BROWSER_PROFILE": "/tmp/my-custom-profile"
      }
    }
  }
}

Troubleshooting

"No Chrome/Chromium browser found"

The server provides helpful error messages with multiple solutions:

Option 1 - Install system Chrome/Chromium (Recommended):

# Ubuntu/Debian
sudo apt install google-chrome-stable
# or
sudo apt install chromium-browser

# Fedora
sudo dnf install google-chrome-stable

# macOS
brew install --cask google-chrome

Option 2 - Install Playwright's Chromium:

npm install playwright
npx playwright install chromium

Option 3 - Use with Antigravity:

• Click the Chrome logo (top right) to launch browser

• The MCP server will automatically connect

Check Server Status

Use the browser_health_check tool to verify:

• Which mode is active (Antigravity / System Chrome / Playwright Chromium)

• Playwright source

• Browser profile location

• Current page URL

Check Server Status

Use the browser_health_check tool to verify:

• Connection mode (Antigravity vs Standalone)

• Playwright source

• Browser profile location

• Current page URL

Development

Project Structure

browser-mcp-server/
├── src/index.js                      # Main server entry point
├── src/                              # Source code
│   ├── index.js                      # Main server class
│   ├── browser.js                    # Browser management
│   ├── tools/                        # Tool modules
│   └── utils.js                      # Utilities
├── tests/                            # Test suite
├── plugins/                          # Plugin directory
├── package.json                      # npm package config
├── README.md                         # This file
└── LICENSE                           # MIT license

Testing

# Test server initialization
npm test

# Manual test
echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0.0"}}}' | node src/index.js

Debug Logging

Check /tmp/mcp-browser-server.log for detailed logs:

• Playwright loading attempts

• Browser connection/launch status

• Console capture events

• Tool execution

Technical Details

MCP Protocol

• Implements MCP 2024-11-05 protocol

• JSON-RPC 2.0 over stdio

• Supports initialize, notifications/initialized, tools/list, tools/call

Browser Control

• Uses Playwright for automation

• Connects via Chrome DevTools Protocol (CDP)

• Port 9222 for remote debugging

Chrome Launch Flags

--remote-debugging-port=9222          # Enable CDP
--user-data-dir=/tmp/chrome-mcp-profile  # Isolated profile
--no-first-run                        # Skip setup
--no-default-browser-check            # No popups
--disable-fre                         # No first-run experience
--disable-sync                        # No Google sync
--disable-component-update            # No auto-updates
# + more stability flags

Compatibility

Tested With

• ✅ Antigravity

• ✅ Claude Desktop (macOS, Windows, Linux)

• ✅ Other MCP clients via stdio

Requirements

• Node.js >= 16.0.0

• Playwright ^1.57.0 (installed automatically via npm)

• Chrome/Chromium browser (automatically detected, or uses Playwright's Chromium)

Platforms

• ✅ Linux

• ✅ macOS

• ✅ Windows

Comparison with Other Tools

vs. Puppeteer MCP Servers

• ✅ More tools (63 vs typical 8-10)

• ✅ Console capture built-in

• ✅ Better error messages

• ✅ Hybrid mode (connect OR launch)

vs. Selenium Grid

• ✅ Simpler setup (no grid needed)

• ✅ MCP protocol integration

• ✅ Built for AI agents

• ✅ Lightweight (single process)

vs. Browser Extensions

• ✅ Works headlessly if needed

• ✅ No extension installation

• ✅ Programmable via MCP

• ✅ Works with any MCP client

Contributing

Contributions welcome! Please:

1. Fork the repository

2. Create a feature branch

3. Make your changes

4. Submit a pull request

License

MIT License - see LICENSE file

Credits

• Built with Playwright

• Implements Model Context Protocol

• Originally developed for Antigravity

Support

• 🐛 Report Issues

• 💬 Discussions

• 📧 Contact: Via GitHub Issues

Changelog

v1.4.0 (2026-01-01) ⭐ NEW

• ✅ Full Power User Suite: Added 26 CDP-based tools for performance, network, security, and storage analysis (63 tools total)

• ✅ Version Unification: Centralized version management to use package.json as the single source of truth

• ✅ Performance Profiling: Added CPU profiling, heap snapshots, and web vitals monitoring

• ✅ Network Analysis: Added request monitoring, HAR export, and WebSocket inspection

• ✅ Security Testing: Added security header inspection, CSP monitoring, and certificate details

• ✅ Storage Inspection: Added IndexedDB, Cache Storage, and Service Worker management

v1.3.0 (2025-12-27)

• ✅ On-Demand Documentation: New browser_docs tool provides detailed specs, return schemas, examples, and caveats for all 37 tools

• ✅ Modular Architecture: Complete refactor into src/ modules for better maintainability

• ✅ Plugin System: New plugins/ directory for extending functionality

• ✅ Improved Testing: Dedicated tests/ directory with fixtures

• ✅ Core Stability: Separated browser logic, tools, and protocol handling

• ✅ Token Efficient: Documentation loaded on-demand, keeping tool descriptions concise

v1.2.0 (2025-12-27)

• ✅ Media Awareness: Added audio/video inspection, spectral analysis, and control tools (36 tools total)

• ✅ Tool: browser_get_media_summary, browser_get_audio_analysis, browser_control_media

v1.1.0 (2025-12-27)

• ✅ Tool Parity: Achieved parity with browser-subagent (33 tools total)

• ✅ Multi-Page: Added support for multiple browser tabs/pages

• ✅ Low-Level Control: Added keyboard/mouse event tools (pixel-based)

• ✅ Utilities: Added reload, go_back, go_forward, wait, hover, focus, select

• ✅ Testing: Updated test suites to include new tools

v1.0.3 (2025-12-26)

• ✅ Documentation: Updated README with v1.0.2 features and clearer installation instructions

• ✅ Code Comments: Updated header to reflect universal compatibility and all features

• ✅ Package Files: Included test suites and changelog in npm package

v1.0.2 (2025-12-26)

• ✅ Smart Chrome Detection: Automatically finds system Chrome/Chromium across Linux, macOS, Windows

• ✅ Three-Tier Strategy: Antigravity Chrome → System Chrome → Playwright Chromium

• ✅ Auto-Install: Playwright now installed automatically as dependency (via npm)

• ✅ Better Errors: Helpful error messages with platform-specific installation instructions

• ✅ Resource Efficient: Uses system Chrome when available (~275MB savings)

• ✅ Test Suites: Includes comprehensive test scripts

• ✅ Auto-Reconnect: Improved browser disconnection handling

• ✅ Documentation: Added detailed CHANGELOG-v1.0.2.md

v1.0.1 (2025-12-26)

• ✅ Fixed CLI bin path for npm installation

• ✅ Improved package configuration

v1.0.0 (2025-12-26)

• ✅ Initial release

• ✅ 16 browser automation tools

• ✅ Console capture (start/get/clear)

• ✅ Hybrid mode (connect OR launch)

• ✅ Safe Chrome launch with isolated profile

• ✅ Multi-source Playwright loading

• ✅ Universal compatibility (Antigravity + Claude Desktop + more)

Made with ❤️ for the MCP community