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

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

Tab Management

Keyboard

Mouse & Interaction

Screenshots

Both return an image content block.

DevTools — Sources

DevTools — Modify

DevTools — Network

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

DevTools — Console

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