Browser MCP

An MCP server + Chrome extension that gives coding agents (Claude Code, etc.) full control over a real Chrome browser. Multiple Claude Code sessions can share the same browser simultaneously.

Architecture

Claude Code #1 → MCP Server #1 ──┐
Claude Code #2 → MCP Server #2 ──┤  (pipe clients)
Claude Code #3 → MCP Server #3 ──┘
                                  │  Named pipe
                                  ▼
                    relay.js  (pipe server, spawned by Chrome)
                                  │  Chrome Native Messaging
                                  ▼
                    background.js  (Chrome Extension Service Worker)
                                  │  Chrome Extension APIs
                                  ▼
                              Web Pages

The relay acts as a named pipe server. Each Claude Code session spawns its own MCP server process, which connects to the relay as a pipe client. The relay multiplexes requests and routes responses back to the correct MCP client by matching request IDs.

Prerequisites

• Node.js 18+ (must be in your system PATH)
• Chrome or Edge browser
• Claude Code (or any MCP-compatible client)

Setup

Step 1: Install dependencies and build

cd /path/to/browser-mcp
npm install
npm run build

This installs the MCP SDK and compiles the TypeScript server to dist/mcp-server.js.

macOS note: Do not keep this project in the ~/Downloads/ folder. macOS System Policy blocks Chrome from launching native messaging hosts located in ~/Downloads/. Move the project elsewhere first (e.g. ~/browser-mcp or ~/Projects/browser-mcp).

Step 2: Load the Chrome extension

1. Open Chrome and navigate to chrome://extensions
2. Enable Developer mode using the toggle in the top-right corner
3. Click Load unpacked
4. Select the extension/ folder inside this project (e.g. C:\Browser MCP\extension)
5. The extension "Browser MCP Bridge" will appear — copy the Extension ID shown underneath it

• It looks like: abcdefghijklmnopqrstuvwxyz012345

Step 3: Register the native messaging host

Run the installer script, passing your extension ID from the previous step:

node install.js <your-extension-id>

For example:

node install.js abcdefghijklmnopqrstuvwxyz012345

This does two things:

• Writes a native messaging host manifest file to the appropriate directory for each supported browser (Chrome, Chrome Canary, Edge, Edge Canary on macOS; Chrome, Edge on Windows/Linux)
• On Windows, registers the manifest path in the Windows registry
• Cleans up any stale relay processes or socket files from previous installations

Important: If you ever reinstall the extension and get a new extension ID, re-run this command with the new ID.

Step 4: Reload the extension

After running the installer, go back to chrome://extensions and click the reload button (circular arrow) on the Browser MCP Bridge extension. This allows the extension to pick up the newly registered native messaging host.

Step 5: Add the MCP server to Claude Code

Option A — CLI command:

claude mcp add browser-mcp -- node "C:/Browser MCP/dist/mcp-server.js"

Option B — Add manually to your Claude Code config file (.claude.json in your project root, or the global claude_desktop_config.json):

{
  "mcpServers": {
    "browser-mcp": {
      "command": "node",
      "args": ["C:/Browser MCP/dist/mcp-server.js"]
    }
  }
}

Step 6: Verify it works

Start a new Claude Code session and ask it something like:

"Open https://example.com in the browser and get the page text"

You should see a new tab open in Chrome and Claude returning the page content.

After Setup

Once setup is complete, you generally don't need to do anything when starting new sessions:

Available Tools

Usage Patterns

Web search

1. browser_open    → navigate to https://www.bing.com
2. browser_state   → find the search input element index
3. browser_input   → type the search query into the input
4. browser_keys    → press Enter to submit
5. browser_state   → read the search result links and snippets
6. browser_open    → navigate to a promising result URL
7. browser_get_text → extract the page content

Read a web page

1. browser_open    → navigate to the URL
2. browser_get_text → extract readable text content

Fill out a form

1. browser_open    → navigate to the form page
2. browser_state   → get element indices for all form fields
3. browser_input   → fill each field by its index
4. browser_click   → click the submit button

How It Works

1. Chrome Extension (extension/background.js) — A Manifest V3 service worker that controls Chrome tabs using the Extensions API. It connects to a native messaging host on load and executes browser commands (open, click, type, etc.) received over that channel.

1. Relay (relay/relay.js) — A small Node.js process spawned by Chrome as a native messaging host. It creates a named pipe server (\\.\pipe\browser-mcp-bridge on Windows) and bridges between Chrome's native messaging protocol (length-prefixed JSON on stdin/stdout) and the named pipe (newline-delimited JSON). It tracks which pipe client sent each request and routes responses back correctly.

1. MCP Server (dist/mcp-server.js) — A Node.js process spawned by Claude Code for each session. It connects to the relay's named pipe as a client, registers 16 browser tools via the MCP protocol over stdio, and translates MCP tool calls into relay requests. Multiple MCP server instances can connect simultaneously.

1. Request flow: MCP Client → MCP Server → Named Pipe → Relay → Chrome Native Messaging → Extension → Chrome Browser → response flows back the same path.

Troubleshooting

"Browser extension not connected"

This means the MCP server couldn't connect to the relay's named pipe. Possible causes:

1. Extension not loaded — Go to chrome://extensions and verify "Browser MCP Bridge" is listed and enabled
2. Native messaging host not registered — Re-run node install.js <extension-id>
3. Extension needs reload — Click the reload button on the extension card in chrome://extensions
4. Chrome not running — The relay only exists while Chrome is running with the extension loaded

Extension loads but tools don't work

• Click "Inspect views: service worker" on the extension card in chrome://extensions to open the console
• Look for [BMCP-Bridge] log messages to diagnose connection issues

Native messaging errors

• Verify Node.js is in your system PATH: run node --version from a terminal
• On Windows, verify registry entries exist:
• HKCU\Software\Google\Chrome\NativeMessagingHosts\com.browser.mcp.relay
• HKCU\Software\Microsoft\Edge\NativeMessagingHosts\com.browser.mcp.relay
• Re-run node install.js <extension-id> to regenerate the manifest and registry entries

macOS-specific issues

• "Native host has exited" immediately after connecting — Check if the project is located in ~/Downloads/. macOS System Policy blocks Chrome's native messaging subprocess from reading files in ~/Downloads/. Move the project to another location (e.g. ~/browser-mcp) and re-run node install.js.
• Quarantine attributes — Files downloaded from the internet have quarantine extended attributes that may block execution. Remove them with:

  xattr -dr com.apple.quarantine /path/to/browser-mcp/

• Node.js not found by Chrome — Chrome launches native messaging hosts with a minimal PATH (/usr/bin:/bin:/usr/sbin:/sbin) that doesn't include Homebrew (/opt/homebrew/bin) or nvm directories. The installer automatically resolves the absolute path to node and writes it into relay.sh. If you change your Node.js installation, re-run node install.js.
• Check relay logs — The relay writes diagnostic logs to /tmp/browser-mcp-relay.log (or $TMPDIR/browser-mcp-relay.log). Check this file for errors:

  cat /tmp/browser-mcp-relay.log

• Stale relay process — If a previous relay process is still running, the new one will exit with EADDRINUSE. Re-running node install.js automatically cleans up stale processes, or manually:

  pkill -f relay.js
  rm -f /tmp/browser-mcp-bridge.sock

Multiple Claude Code sessions

All sessions share the same browser. Tabs opened by one session are visible to others via browser_sessions. If two sessions try to interact with the same tab simultaneously, results may be unpredictable — each session should work with its own tabs.

Project Structure

Browser MCP/
├── src/
│   └── mcp-server.ts       # MCP server (pipe client + tool definitions)
├── dist/
│   └── mcp-server.js       # Compiled server (this is what Claude Code runs)
├── extension/
│   ├── manifest.json        # Chrome MV3 extension manifest
│   ├── background.js        # Service worker — executes browser commands
│   └── content.js           # Fallback content extraction script
├── relay/
│   ├── relay.js             # Native messaging relay (pipe server + request router)
│   ├── relay.bat            # Windows wrapper for relay.js
│   └── relay.sh             # macOS/Linux wrapper for relay.js (generated by install.js)
├── install.js               # One-time setup: registers native messaging host
├── package.json
└── tsconfig.json