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.
- ✅ 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
| 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)%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
# Install globally (Playwright installs automatically)
npm install -g @ricardodeazambuja/browser-mcp-server
# Or use directly with npx (no installation needed)
npx @ricardodeazambuja/browser-mcp-serverNote: 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.
# 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# 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 chromiumAdd 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.
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.
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.jsUsing 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-serverVerify installation:
# List all MCP servers
claude mcp list
# Check server status
claude mcp get browserExample 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_screenshotNote: 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.
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.jsUsing 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-serverManagement commands:
# List all configured MCP servers
gemini mcp list
# Remove the server if needed
gemini mcp remove browserExample 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 automaticallyAdvanced 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- browser_docs(toolName?) - Get detailed docs, return schemas, examples, and caveats for any tool
- browser_list_pages() - List all open tabs/pages
- browser_new_page(url?) - Open a new tab
- browser_switch_page(index) - Switch active tab
- browser_close_page(index?) - Close a tab
- browser_get_media_summary() - List all audio/video elements with state
- browser_get_audio_analysis(durationMs?, selector?) - Analyze audio output (volume, spectrum)
- browser_control_media(selector, action, value?) - Play, pause, mute, seek
- browser_navigate(url) - Navigate to a URL
- browser_click(selector) - Click an element (selector-based)
- browser_type(selector, text) - Type text into an input
- browser_scroll(x?, y?) - Scroll the page (generic)
- browser_reload() - Reload current page
- browser_go_back() - Navigate back
- browser_go_forward() - Navigate forward
- browser_wait(ms) - Pause execution
- browser_mouse_move(x, y) - Move mouse to pixel coordinates
- browser_mouse_click(x?, y?, button?, count?) - Click at pixel coordinates
- browser_mouse_drag(fromX, fromY, toX, toY) - Drag and drop
- browser_mouse_wheel(deltaX, deltaY) - Scroll mouse wheel
- browser_press_key(key) - Send keyboard event (e.g. "Enter")
- browser_screenshot(fullPage?) - Capture screenshot
- browser_get_text(selector) - Get text from element
- browser_get_dom(selector?) - Get DOM structure
- browser_read_page() - Get page metadata (title, URL)
- browser_evaluate(code) - Execute JavaScript
- browser_console_start(level?) - Start capturing logs
- browser_console_get(filter?) - Get captured logs
- browser_console_clear() - Clear logs and stop
- browser_hover(selector) - Hover over element
- browser_focus(selector) - Focus element
- browser_select(selector, values) - Select dropdown options
- browser_wait_for_selector(selector, timeout?) - Wait for element
- browser_resize_window(width, height) - Resize window
- browser_start_video_recording(path?) - Start session recording
- browser_stop_video_recording() - Stop and save recording
- browser_health_check() - Verify browser connection
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.
- browser_perf_start_profile(sampleInterval?) - Start CPU profiling
- browser_perf_stop_profile() - Get CPU profile data with summary
- browser_perf_take_heap_snapshot(reportProgress?) - Capture memory snapshot
- browser_perf_get_heap_usage() - Current JavaScript heap statistics
- browser_perf_get_metrics() - Runtime metrics (DOM nodes, listeners, etc.)
- browser_perf_get_performance_metrics() - Web vitals (FCP, LCP, CLS, TTFB)
- browser_perf_start_coverage(resetOnNavigation?) - Track code coverage
- browser_perf_stop_coverage() - Get coverage results
Use Cases: Memory leak detection, CPU profiling, performance optimization, code coverage analysis, web vitals monitoring
- browser_net_start_monitoring(patterns?) - Monitor network requests
- browser_net_get_requests(filter?) - Get captured requests with timing
- browser_net_stop_monitoring() - Stop monitoring and clear log
- browser_net_export_har(includeContent?) - Export HTTP Archive log
- browser_net_get_websocket_frames(requestId) - Inspect WebSocket frames
- browser_net_set_request_blocking(patterns) - Block URL patterns
- browser_net_emulate_conditions(offline, latency, download, upload) - Network throttling
Use Cases: API debugging, HAR export, WebSocket debugging, performance testing, request blocking, network throttling
- browser_sec_get_security_headers() - Inspect security HTTP headers
- browser_sec_get_certificate_info() - TLS/SSL certificate details
- browser_sec_detect_mixed_content() - Find HTTP resources on HTTPS pages
- browser_sec_start_csp_monitoring() - Monitor CSP violations
- browser_sec_get_csp_violations() - Get violation log
- browser_sec_stop_csp_monitoring() - Stop monitoring
Use Cases: Security audits, CSP debugging, HTTPS migration, certificate validation, mixed content detection
- browser_storage_get_indexeddb(databaseName?, objectStoreName?) - Inspect IndexedDB
- browser_storage_get_cache_storage(cacheName?) - List Cache Storage entries
- browser_storage_delete_cache(cacheName) - Delete cache
- browser_storage_get_service_workers() - Service worker state
- browser_storage_unregister_service_worker(scopeURL) - Unregister worker
Use Cases: IndexedDB inspection, Cache Storage management, Service Worker debugging, offline functionality testing
// 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' }).
The browser_docs tool provides comprehensive documentation for all browser tools without increasing token overhead in normal operations.
- 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
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
// 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, ...📖 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' })
// Agent uses:
browser_navigate("https://example.com")
browser_screenshot(fullPage: true)// Agent uses:
browser_console_start()
browser_navigate("https://myapp.com")
browser_click("#submit-button")
browser_console_get(filter: "error")
// Shows: ❌ [ERROR] Uncaught TypeError: ...// 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// 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// Agent uses:
browser_mouse_move(500, 300)
browser_mouse_click(button: "right")
browser_press_key("Enter")// 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 toolsThe 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
- Isolated Profile: Uses
/tmp/chrome-mcp-profile(not your personal Chrome!) - No Setup Dialogs: Silent startup with
--no-first-runflags - Clean Environment: No extensions, sync, or background updates
- Reproducible: Same behavior across systems
This MCP server provides powerful browser automation capabilities. Please review these security considerations:
- Uses
/tmp/chrome-mcp-profileby default (configurable viaMCP_BROWSER_PROFILE) - Does NOT access your personal Chrome data (cookies, passwords, history)
- Each instance runs in a clean, isolated environment
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
- 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
- ✅ 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
# Custom browser profile location (optional)
export MCP_BROWSER_PROFILE="$HOME/.mcp-browser-profile"
# Then run the server
node src/index.js{
"mcpServers": {
"browser-tools": {
"command": "node",
"args": ["/path/to/src/index.js"],
"env": {
"MCP_BROWSER_PROFILE": "/tmp/my-custom-profile"
}
}
}
}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-chromeOption 2 - Install Playwright's Chromium:
npm install playwright
npx playwright install chromiumOption 3 - Use with Antigravity:
- Click the Chrome logo (top right) to launch browser
- The MCP server will automatically connect
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
Use the browser_health_check tool to verify:
- Connection mode (Antigravity vs Standalone)
- Playwright source
- Browser profile location
- Current page URL
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
# 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.jsCheck /tmp/mcp-browser-server.log for detailed logs:
- Playwright loading attempts
- Browser connection/launch status
- Console capture events
- Tool execution
- Implements MCP 2024-11-05 protocol
- JSON-RPC 2.0 over stdio
- Supports
initialize,notifications/initialized,tools/list,tools/call
- Uses Playwright for automation
- Connects via Chrome DevTools Protocol (CDP)
- Port 9222 for remote debugging
--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- ✅ Antigravity
- ✅ Claude Desktop (macOS, Windows, Linux)
- ✅ Other MCP clients via stdio
- Node.js >= 16.0.0
- Playwright ^1.57.0 (installed automatically via npm)
- Chrome/Chromium browser (automatically detected, or uses Playwright's Chromium)
- ✅ Linux
- ✅ macOS
- ✅ Windows
- ✅ More tools (63 vs typical 8-10)
- ✅ Console capture built-in
- ✅ Better error messages
- ✅ Hybrid mode (connect OR launch)
- ✅ Simpler setup (no grid needed)
- ✅ MCP protocol integration
- ✅ Built for AI agents
- ✅ Lightweight (single process)
- ✅ Works headlessly if needed
- ✅ No extension installation
- ✅ Programmable via MCP
- ✅ Works with any MCP client
Contributions welcome! Please:
- Fork the repository
- Create a feature branch
- Make your changes
- Submit a pull request
MIT License - see LICENSE file
- Built with Playwright
- Implements Model Context Protocol
- Originally developed for Antigravity
- 🐛 Report Issues
- 💬 Discussions
- 📧 Contact: Via GitHub Issues
- ✅ 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.jsonas 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
- ✅ On-Demand Documentation: New
browser_docstool 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
- ✅ 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
- ✅ 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
- ✅ 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
- ✅ 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
- ✅ Fixed CLI bin path for npm installation
- ✅ Improved package configuration
- ✅ 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