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

| Installation Method | Best For | Setup Time | |-------------------|----------|------------| | NPM Package | Production use, easy updates | 30 seconds | | Clone Repository | Development, contributing | 2 minutes | | Direct Download | Quick testing, minimal setup | 1 minute |

| MCP Client | Config File Location | |------------|---------------------| | Claude Desktop | ~/Library/Application Support/Claude/claude_desktop_config.json (macOS)<br>%APPDATA%/Claude/claude_desktop_config.json (Windows) | | Antigravity | ~/.gemini/antigravity/mcp_config.json | | Claude Code | Use claude mcp add command | | Gemini CLI | Use gemini mcp add command |

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_vi