loading…
Search for a command to run...
loading…
A universal browser automation MCP server using Playwright, enabling programmatic control of Chrome with 63 tools for navigation, interaction, media control, an
A universal browser automation MCP server using Playwright, enabling programmatic control of Chrome with 63 tools for navigation, interaction, media control, and CDP-based diagnostics.
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.
| 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:
# 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.
# 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 chromium
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.
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.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.
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
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.
Use Cases: Memory leak detection, CPU profiling, performance optimization, code coverage analysis, web vitals monitoring
Use Cases: API debugging, HAR export, WebSocket debugging, performance testing, request blocking, network throttling
Use Cases: Security audits, CSP debugging, HTTPS migration, certificate validation, mixed content detection
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.
When calling browser_docs(toolName), you receive:
// 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: '[email protected]' })
// 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 tools
The server automatically chooses the best browser option:
Tier 1 - Antigravity Mode:
Tier 2 - System Chrome/Chromium:
/usr/bin/google-chrome, /usr/bin/chromium, etc./tmp/chrome-mcp-profile)Tier 3 - Playwright Chromium:
npx playwright install chromium/tmp/chrome-mcp-profile)/tmp/chrome-mcp-profile (not your personal Chrome!)--no-first-run flagsThis MCP server provides powerful browser automation capabilities. Please review these security considerations:
/tmp/chrome-mcp-profile by default (configurable via MCP_BROWSER_PROFILE)browser_evaluate: Executes arbitrary JavaScript in the browser context
browser_navigate: Navigates to any URL
/tmp/mcp-browser-server.log/tmp)# 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-chrome
Option 2 - Install Playwright's Chromium:
npm install playwright
npx playwright install chromium
Option 3 - Use with Antigravity:
Use the browser_health_check tool to verify:
Use the browser_health_check tool to verify:
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.js
Check /tmp/mcp-browser-server.log for detailed logs:
initialize, notifications/initialized, tools/list, tools/call--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
Contributions welcome! Please:
MIT License - see LICENSE file
package.json as the single source of truthbrowser_docs tool provides detailed specs, return schemas, examples, and caveats for all 37 toolssrc/ modules for better maintainabilityplugins/ directory for extending functionalitytests/ directory with fixturesbrowser_get_media_summary, browser_get_audio_analysis, browser_control_mediabrowser-subagent (33 tools total)reload, go_back, go_forward, wait, hover, focus, selectMade with ❤️ for the MCP community
Run in your terminal:
claude mcp add browser-mcp-server -- npx Security
Low riskAutomated heuristic from public metadata — not a security guarantee.