BrowserGenie MCP Server

An MCP (Model Context Protocol) server that gives AI models full control over a Chrome browser. It pairs with the BrowserGenie Extension to expose 30+ browser automation tools over stdio — navigation, clicking, typing, screenshots, and complete DevTools access.

Two-repo setup: This is the server half. The Chrome extension lives in a separate repository. Both are required.

How It Works

AI Client (Claude, Cursor, etc.)
    │  stdio  (JSON-RPC / MCP)
    ▼
MCP Server  ◄── this repo
    │  WebSocket  ws://localhost:7890
    ▼
Chrome Extension
    ├── chrome.tabs         → Navigation, tab management
    ├── chrome.debugger     → DevTools Protocol (CDP)
    ├── chrome.scripting    → Content script injection
    ├── chrome.cookies      → Cookie management
    └── Content Scripts      → Real DOM event simulation

The MCP server bridges your AI client (over stdio) and the Chrome extension (over WebSocket). Every MCP tool call is forwarded to the extension, executed in the browser, and the result is returned to the AI client.

Requirements

• Node.js 18+
• npm
• The companion BrowserGenie Extension installed in Chrome

Installation

Option A — Run from source

git clone https://github.com/BrowserGenie/mcp.git
cd mcp
npm install
npm run build

Option B — npx (once published)

npx browser-genie-mcp

Configuration

Add the server to your AI client's MCP configuration.

Claude Desktop

File: ~/Library/Application Support/Claude/claude_desktop_config.json (macOS)
File: %APPDATA%\Claude\claude_desktop_config.json (Windows)

{
  "mcpServers": {
    "browser-genie": {
      "command": "node",
      "args": ["/absolute/path/to/browser-genie-mcp-server/dist/index.js"]
    }
  }
}

Claude Code

File: ~/.claude/settings.json or project-level .mcp.json:

{
  "mcpServers": {
    "browser-genie": {
      "command": "node",
      "args": ["/absolute/path/to/browser-genie-mcp-server/dist/index.js"]
    }
  }
}

Cursor / other MCP clients

{
  "mcpServers": {
    "browser-genie": {
      "command": "node",
      "args": ["/absolute/path/to/browser-genie-mcp-server/dist/index.js"]
    }
  }
}

After saving the config, restart your AI client.

Environment Variables

Variable	Default	Description
WEBSOCKET_PORT	7890	Port the WebSocket server listens on. The extension must use the same port.

Pass via the MCP config env block:

{
  "mcpServers": {
    "browser-genie": {
      "command": "node",
      "args": ["/path/to/dist/index.js"],
      "env": { "WEBSOCKET_PORT": "8080" }
    }
  }
}

If you change the port, also update WEBSOCKET_URL in constants.ts inside the extension repo.

Verifying the Connection

Once the server is running and the extension is loaded in Chrome, click the extension icon. The popup should show a green Connected indicator. If it shows Disconnected, ensure the MCP server process is running.

MCP Tools Reference

Every tool accepts an optional apiKey (string) when authentication is enabled in the extension popup, and an optional tabId (number) to target a specific tab (defaults to the active tab).

Navigation

Tool	Description	Key Parameters
navigate_to_url	Navigate to a URL	url (required)
navigate_back	Go back in history	—
navigate_forward	Go forward in history	—
navigate_reload	Reload the page	ignoreCache (bool)

Tab Management

Tool	Description	Key Parameters
list_tabs	List all open tabs	—
select_tab	Focus a tab	tabId (required)
new_tab	Open a new tab	url (optional)
close_tab	Close a tab	tabId (required)

Keyboard

Tool	Description	Key Parameters
press_key	Press a key with optional modifiers	key, modifiers[]
type_text	Type text character by character	text, delay (ms)

Mouse & Interaction

Tool	Description	Key Parameters
click_element	Click via coordinates, CSS, or XPath	target.type, target.value, button, doubleClick
input_and_type	Click a field then type	selector, text, clearFirst, submit
drag_and_drop	Drag from one point to another	from, to
hover_element	Hover to trigger CSS states / tooltips	target

Screenshots

Tool	Description	Key Parameters
screenshot_viewport	Capture visible viewport	format, quality
screenshot_full_page	Capture full scrollable page	format, quality

Both return an image content block.

DevTools — Sources

Tool	Description	Key Parameters
read_page_html	Full outerHTML of the page	—
read_stylesheets	CSS stylesheet sources	url (filter)
read_scripts	JavaScript sources	url (filter)
read_page_resources	List all resources with URLs & sizes	type filter

DevTools — Modify

Tool	Description	Key Parameters
modify_html	Live DOM mutation	selector, action, value, attributeName
modify_css	Set inline styles	selector, styles (object)

DevTools — Network

Tool	Description	Key Parameters
get_network_logs	Get collected request/response logs	filter.urlPattern, filter.method, filter.statusCode
get_network_request_detail	Full details of one request	requestId, includeBody
clear_network_logs	Clear collected logs	—

Network logs are collected from when the debugger attaches. Call any DevTools tool first to trigger attachment before the traffic you want to capture.

DevTools — Storage

Tool	Description
get_cookies / set_cookie / delete_cookie	Cookie CRUD
get_local_storage / set_local_storage / remove_local_storage	localStorage
get_session_storage / set_session_storage / remove_session_storage	sessionStorage

DevTools — Console

Tool	Description	Key Parameters
get_console_logs	Retrieve console messages	level, clear
execute_javascript	Run JS in the page and return result	expression

Project Structure

browser-genie-mcp-server/
├── src/
│   ├── index.ts              # Entry point — stdio MCP transport
│   ├── server.ts             # McpServer setup & tool registration
│   ├── websocket-bridge.ts   # WebSocket server + request/response correlation
│   ├── auth.ts               # API key validation helper
│   ├── types.ts              # Shared types & constants (port, message shapes)
│   └── tools/                # One file per tool category
│       ├── navigation.ts
│       ├── tab-management.ts
│       ├── click.ts
│       ├── input.ts
│       ├── keyboard.ts
│       ├── hover.ts
│       ├── drag-drop.ts
│       ├── screenshot.ts

│       ├── devtools-sources.ts
│       ├── devtools-modify.ts
│       ├── devtools-network.ts
│       ├── devtools-storage.ts
│       └── devtools-console.ts
├── dist/                     # Compiled output (after npm run build)
├── package.json
├── tsconfig.json
├── .gitignore
└── LICENSE

Development

# Watch mode — recompiles on every file save
npm run dev

# One-shot build
npm run build

# Run the compiled server directly
npm start

Important Notes

Debugger Banner

When any DevTools feature is first used on a tab, Chrome shows an "Extension is debugging this browser" banner. This is a Chrome security requirement and cannot be suppressed. The debugger attaches lazily — only when a DevTools tool is first called for that tab.

Service Worker Lifecycle

Chrome MV3 service workers terminate after ~30 seconds of inactivity. The extension uses chrome.alarms to keep the WebSocket alive, with automatic exponential-backoff reconnection (1 s → 2 s → 4 s → … → 30 s max).

Contributing

Contributions are welcome! Please open an issue first to discuss what you'd like to change, then submit a pull request.

1. Fork the repository
2. Create a feature branch: git checkout -b feat/my-feature
3. Commit your changes: git commit -m 'feat: add my feature'
4. Push and open a Pull Request

Related

• BrowserGenie Extension — the Chrome extension that pairs with this server
• Model Context Protocol — the open protocol this server implements

License

Apache License 2.0