Content
<a href="https://browsermcp.io">
<img src="./.github/images/banner.png" alt="Browser MCP banner">
</a>
<h3 align="center">Browser MCP</h3>
<p align="center">
Automate your browser with AI.
<br />
<a href="https://browsermcp.io"><strong>Website</strong></a>
•
<a href="https://docs.browsermcp.io"><strong>Docs</strong></a>
</p>
## About
Browser MCP is an MCP server + browser extension that allows you to automate your browser using AI applications like VS Code, Claude, Cursor, and Windsurf. Supports both **Chrome** and **Firefox**.
This is a fork of the [original Browser MCP](https://github.com/browsermcp/mcp) with the following changes:
- **Standalone build**: All monorepo dependencies (`@repo/*`, `@r2r/messaging`) replaced with local implementations
- **Extended toolset**: 39 tools (up from 12 core tools) including tab management, JavaScript execution, cookie/storage access, CSS injection, network monitoring, and more
- **Cross-browser extension**: Full-featured extension with all 36 command handlers, compatible with both Chrome (MV3) and Firefox (MV3)
- **WSL support**: Auto-detects WSL IP and writes a config file for the extension to discover the correct WebSocket address
- **Connection resilience**: Speed guidance in tool descriptions, connection error detection with retry hints
## Features
- ⚡ Fast: Automation happens locally on your machine, resulting in better performance without network latency.
- 🔒 Private: Since automation happens locally, your browser activity stays on your device and isn't sent to remote servers.
- 👤 Logged In: Uses your existing browser profile, keeping you logged into all your services.
- 🥷🏼 Stealth: Avoids basic bot detection and CAPTCHAs by using your real browser fingerprint.
## Installation
### Prerequisites
- Node.js >= 18
- Google Chrome, Chromium, or Firefox 113+
- The Browser MCP extension (included in `extension/`)
### From source
```bash
git clone https://github.com/IlGabbia998/browsermcp-mcp.git
cd browsermcp-mcp
npm install
npm run build
```
### Load the extension
#### Chrome
1. Open Chrome and navigate to `chrome://extensions`
2. Enable **Developer mode**
3. Click **Load unpacked** and select the `extension/` folder from this project
4. The extension will show in your toolbar — click it and hit **Reconnect** when the MCP server is running
#### Firefox
Firefox MV3 requires a different `background` entry than Chrome. You must switch the manifest before loading the extension.
Using the helper script (recommended):
```bash
npm run use:firefox
```
Or manually:
1. Copy `extension/manifest.firefox.json` to `extension/manifest.json` (replacing the Chrome one)
Then load it:
2. Open Firefox and navigate to `about:debugging#/runtime/this-firefox`
3. Click **Load Temporary Add-on...**
4. Select `extension/manifest.json` from this project
5. The extension will show in your toolbar — click it and hit **Connect** when the MCP server is running
> **Note:** Chrome and Firefox use different manifest formats for MV3. Use `manifest.json` for Chrome (default) and run `npm run use:firefox` (or copy `manifest.firefox.json`) for Firefox. Firefox temporary add-ons are removed when Firefox is restarted. To restore the Chrome manifest, run `npm run use:chrome`.
### Using in your MCP client
Add the server to your MCP client config. The built entry point is `dist/index.js`.
#### Claude Desktop
Edit `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):
```json
{
"mcpServers": {
"browser": {
"command": "node",
"args": ["/absolute/path/to/browsermcp-mcp/dist/index.js"]
}
}
}
```
#### opencode
Add to your `opencode.json`:
```json
{
"mcp": {
"browser": {
"type": "local",
"command": ["node", "/absolute/path/to/browsermcp-mcp/dist/index.js"],
"enabled": true
}
}
}
```
#### Cursor / Windsurf
Add to your MCP settings (`.cursor/mcp.json` or equivalent):
```json
{
"mcpServers": {
"browser": {
"command": "node",
"args": ["/absolute/path/to/browsermcp-mcp/dist/index.js"]
}
}
}
```
### Connect the browser
1. Start the MCP server (via your MCP client or `node dist/index.js`)
2. Open Chrome/Firefox and click the Browser MCP extension icon in the toolbar
3. Click **Reconnect** — the extension auto-discovers the server address
4. The MCP server will detect the connection automatically
## Available Tools (39)
### Core
| Tool | Description |
|------|-------------|
| `browser_navigate` | Navigate to a URL |
| `browser_go_back` | Navigate back |
| `browser_go_forward` | Navigate forward |
| `browser_snapshot` | Capture an accessibility snapshot of the page |
| `browser_click` | Click an element (by ref or description) |
| `browser_hover` | Hover over an element |
| `browser_type` | Type text into an input field |
| `browser_select_option` | Select an option in a dropdown |
| `browser_drag` | Drag from one element to another |
| `browser_press_key` | Press a keyboard key |
| `browser_wait` | Wait for N seconds |
| `browser_screenshot` | Take a screenshot |
| `browser_get_console_logs` | Get browser console logs |
### Navigation & Tabs
| Tool | Description |
|------|-------------|
| `browser_scroll` | Scroll the page (up/down/left/right) |
| `browser_new_tab` | Open a new tab |
| `browser_reload` | Reload the current page |
| `browser_list_tabs` | List all open tabs |
| `browser_close_tab` | Close a tab by ID |
| `browser_switch_tab` | Switch to a tab by ID |
### Page Interaction
| Tool | Description |
|------|-------------|
| `browser_find_text` | Find text content on the page |
| `browser_execute_js` | Execute arbitrary JavaScript |
| `browser_get_links` | Extract all links from the page |
| `browser_get_elements` | Query elements by CSS selector |
| `browser_extract_table` | Extract table data as structured JSON |
| `browser_extract_meta` | Extract page metadata and OpenGraph tags |
| `browser_extract_images` | Extract all images from the page |
| `browser_right_click` | Right-click an element |
| `browser_double_click` | Double-click an element |
| `browser_highlight` | Highlight elements matching a selector |
| `browser_readability` | Extract main article content |
| `browser_wait_for` | Wait for an element to appear |
| `browser_get_computed_style` | Get computed CSS styles for an element |
| `browser_inject_css` | Inject custom CSS into the page |
### Storage & Cookies
| Tool | Description |
|------|-------------|
| `browser_get_cookies` | Get cookies for the current page |
| `browser_set_cookies` | Set a cookie |
| `browser_get_storage` | Read from localStorage or sessionStorage |
| `browser_set_storage` | Write to localStorage or sessionStorage |
### Monitoring
| Tool | Description |
|------|-------------|
| `browser_network_log` | Start/stop/query network request logging |
| `browser_console_log` | Start/stop/query console log interception |
## Usage examples
Ask your AI assistant to do things like:
- "Go to github.com and take a screenshot"
- "Click the login button and fill in my email"
- "Scroll down and click the next page link"
- "Extract all links from this page"
- "Show me the cookies for this site"
- "Run JavaScript to get the page title"
- "Monitor network requests while I navigate"
- "Inject a custom CSS theme on this page"
The AI uses accessibility snapshots to understand the page structure and interact with elements reliably.
## Contributing
This is a standalone build of the Browser MCP server, extracted from the original monorepo. All monorepo dependencies have been replaced with local implementations.
### Project structure
```
src/
index.ts # Entry point, tool registration
server.ts # MCP server with connection error handling
context.ts # WebSocket context management
ws.ts # WebSocket server creation
lib/
config/ # App and MCP configuration
messaging/ # WebSocket message sender
types/ # Zod schemas for all tools
tools/
snapshot.ts # Core interaction tools (click, type, hover, etc.)
common.ts # Navigation tools (navigate, goBack, etc.)
custom.ts # Screenshot, console logs
extended.ts # All extended tools (26 new tools)
tool.ts # Tool type definitions
utils/
port.ts # Port utilities
aria-snapshot.ts # Accessibility snapshot capture
extension/
background.js # Cross-browser service worker (36 command handlers)
manifest.json # Extension manifest (MV3, Chrome + Firefox compatible)
popup.html # Extension popup UI
popup.js # Popup JavaScript
icons/ # Extension icons
```
## Credits
Browser MCP was adapted from the [Playwright MCP server](https://github.com/microsoft/playwright-mcp) in order to automate the user's browser rather than creating new browser instances. This allows using the user's existing browser profile to use logged-in sessions and avoid bot detection mechanisms that commonly block automated browser use.
