Click on "Install 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., "@Browser MCP Servernavigate to news.google.com and summarize the top headlines for me"
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.
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 |
|
Antigravity |
|
Claude Code | Use |
Gemini CLI | Use |
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)
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)
Method 3: Direct Download (Single File)
Usage with Claude Desktop
Add to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):
Using local installation:
Using NPM:
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:
Using NPM:
Then refresh MCP servers in Antigravity.
Usage with Claude Code
Add the browser-mcp-server using the Claude CLI:
Using local installation:
Using NPM:
Verify installation:
Example usage in Claude Code:
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:
Using NPM:
Management commands:
Example usage in Gemini CLI:
Advanced options:
Available Tools (63)
Documentation
browser_docs(toolName?) - Get detailed docs, return schemas, examples, and caveats for any tool
Multi-Page Management
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
Media Awareness & Control
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
Navigation & Interaction
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
Low-Level Interaction
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")
Information Gathering
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
Console Debugging
browser_console_start(level?) - Start capturing logs
browser_console_get(filter?) - Get captured logs
browser_console_clear() - Clear logs and stop
Advanced Interaction
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
🔬 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)
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
Network Analysis (7 tools)
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
Security Testing (6 tools)
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
Storage & Service Workers (5 tools)
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
Getting Started with CDP Tools
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
Example Output
Examples
Navigate and Screenshot
Debug JavaScript Errors
Media Monitoring & Control
Multi-Tab Automation
Pixel-Based Interaction
Get Tool Documentation
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 chromiumUses 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-runflagsClean 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-profileby default (configurable viaMCP_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.logLogs 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
MCP Config with Environment Variables
Troubleshooting
"No Chrome/Chromium browser found"
The server provides helpful error messages with multiple solutions:
Option 1 - Install system Chrome/Chromium (Recommended):
Option 2 - Install Playwright's 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
Testing
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
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:
Fork the repository
Create a feature branch
Make your changes
Submit a pull request
License
MIT License - see LICENSE file
Credits
Built with Playwright
Implements Model Context Protocol
Originally developed for Antigravity
Support
📧 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.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
v1.3.0 (2025-12-27)
✅ 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
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