Browser Bridge

A Chrome extension that exposes Chrome browser APIs as MCP (Model Context Protocol) tools, enabling AI assistants like Claude Desktop to interact with your browser.

Architecture

Browser Bridge uses WebSocket communication between the extension and local server:

• Chrome Extension (background service worker) - Handles Chrome API calls, communicates via WebSocket
• Server (Node.js process) - Runs WebSocket server for extension communication and MCP server
• MCP Server - Exposes browser tools via MCP protocol (HTTP or stdio transport)
• MCP Client (external, e.g., Claude Desktop) - Connects to the MCP server

MCP Client (Claude Desktop or HTTP client)
    ↕ (stdio or HTTP/SSE)
MCP Server (Node.js)
    ↕ (WebSocket - port 58080)
Chrome Extension (Service Worker)
    ↕ (Chrome APIs)
Browser (Tabs/Bookmarks/History)

Key Design Decision: Chrome extension communication uses WebSocket instead of native messaging, freeing up stdin/stdout for MCP stdio transport (required for Claude Desktop compatibility). WebSocket provides reliable bidirectional communication that works well in Chrome extension service workers.

Features

Tab Management

• chrome_list_tabs - List all open tabs
• chrome_open_tab - Open a new tab
• chrome_close_tab - Close tabs
• chrome_query_tabs - Search/filter tabs
• chrome_update_tab - Update tab properties (URL, muted, etc.)
• chrome_group_tabs - Organize tabs into groups
• chrome_move_tab - Move a tab to a new position or window
• chrome_ungroup_tabs - Remove tabs from their groups
• chrome_get_tab - Get a tab by its ID

Bookmark Management

• chrome_create_bookmark - Create a bookmark
• chrome_delete_bookmark - Delete bookmarks
• chrome_search_bookmarks - Search bookmarks
• chrome_update_bookmark - Update bookmark properties
• chrome_get_bookmark_tree - Get bookmark folder structure
• chrome_get_bookmark - Get a bookmark by its ID
• chrome_get_bookmark_children - Get a folder's direct children
• chrome_get_recent_bookmarks - Get recently added bookmarks
• chrome_get_bookmark_subtree - Get a bookmark and all descendants
• chrome_move_bookmark - Move a bookmark or folder
• chrome_remove_bookmark_tree - Delete a bookmark folder and its contents

History Management

• chrome_search_history - Search browsing history
• chrome_delete_history_url - Delete a specific URL from history
• chrome_delete_history_range - Delete history entries within a time range
• chrome_get_visits - Get all visits for a specific URL
• chrome_get_recent_history - Get recent browsing history
• chrome_clear_all_history - Clear all browsing history

Tab Groups Management

• chrome_get_tab_group - Get details about a specific tab group
• chrome_move_tab_group - Move a tab group to a different position
• chrome_query_tab_groups - Query tab groups based on criteria
• chrome_update_tab_group - Modify tab group properties (title, color, etc.)

Windows Management

• chrome_get_window - Get a window by its ID
• chrome_get_all_windows - Get all windows
• chrome_get_current_window - Get the current window
• chrome_get_last_focused_window - Get the last focused window
• chrome_create_window - Create a new window
• chrome_update_window - Update window properties
• chrome_remove_window - Remove (close) a window

Sessions Management

• chrome_get_recently_closed - Get recently closed tabs and windows

Top Sites

• chrome_get_most_visited - Get the most frequently visited sites

Page Interaction

• chrome_execute_script - Read text, HTML, form values, or attributes using reviewed page-content actions
• chrome_click_element - Click the first element matching a CSS selector
• chrome_type_text - Fill an input, textarea, or contenteditable element
• chrome_insert_css - Insert CSS into a page

Page interaction requires the extension's <all_urls> host permission. The bridge only exposes fixed, structured actions; it does not execute arbitrary JavaScript received from MCP clients.

Navigation State

• chrome_wait_for_navigation - Wait for a tab to reach a navigation milestone
• chrome_get_frames - List the frames in a tab

Screenshot Capture

• chrome_capture_tab - Capture the active tab's visible viewport as a PNG or JPEG image

Downloads

• chrome_search_downloads - Search downloads
• chrome_download_file - Start a download
• chrome_cancel_download - Cancel a download
• chrome_pause_download - Pause a download
• chrome_resume_download - Resume a download
• chrome_open_download - Open a downloaded file
• chrome_show_download_in_folder - Reveal a downloaded file in its folder

Browser UI

• chrome_set_badge - Set the extension action badge
• chrome_show_notification - Show a desktop notification

Prerequisites

• Node.js 24 or higher
• Google Chrome browser
• npm or yarn package manager

Quick Start

1. Install Browser Bridge from the Chrome Web Store once it is published. Until then, download the versioned extension ZIP from the project's release assets, extract it, and load the extracted directory from chrome://extensions/ with Developer mode enabled.
2. Open the extension's Options page, click Generate to create an auth token, then Save.
3. Expand Set up your MCP client, copy the configuration, and paste it into your MCP client. See the MCP local server setup guide.

Example configuration after this package is published as @wpscholar/browser-bridge:

{
  "mcpServers": {
    "browser-bridge": {
      "command": "npx",
      "args": ["--yes", "@wpscholar/browser-bridge"],
      "env": {
        "BROWSER_BRIDGE_AUTH_TOKEN": "replace-with-the-token-from-extension-options"
      }
    }
  }
}

npx downloads and runs the npm package when the MCP client starts. The server starts its localhost WebSocket bridge automatically; do not start host.js alongside this configuration.

See INSTALLATION.md for manual ZIP installation, multiple profiles, HTTP MCP clients, and troubleshooting.

Running from Source

For development, clone the repository and install dependencies:

npm install

Load the extension directory through chrome://extensions/, then start the HTTP MCP server:

BROWSER_BRIDGE_AUTH_TOKEN=replace-with-a-long-random-secret npm start

This starts the extension WebSocket server on ws://127.0.0.1:58080 and the MCP HTTP server on http://127.0.0.1:6001. Configure the same token in the extension Options page (use Generate for a secure random value).

Multiple Chrome Profiles

If you run more than one Chrome profile — or different Chromium-based browsers — configure each one through the extension's Options page. Each profile has its own isolated chrome.storage.local, so its port and auth token do not affect another profile:

1. Start each server instance with a distinct port and token, e.g. BROWSER_BRIDGE_CHROME_PORT=58081 BROWSER_BRIDGE_AUTH_TOKEN=profile1-secret npm start for profile 1, BROWSER_BRIDGE_CHROME_PORT=58082 BROWSER_BRIDGE_AUTH_TOKEN=profile2-secret npm start for profile 2 (or set both in each MCP client config's env field).
2. In each profile, go to chrome://extensions/ → BrowserBridge → Details → Extension options, expand Advanced settings, and set the matching port and auth token.
3. The extension reconnects immediately on save — no reload needed.

Ports are restricted to 58080-58089 (declared in manifest.json's host_permissions); to support more than 10 simultaneous profiles, widen that range and reload the extension.

Connecting MCP Clients

Claude Desktop

✅ Claude Desktop is now supported! The Chrome extension communicates over WebSocket, freeing up stdin/stdout for MCP stdio transport.

The easiest setup path is the extension Options page:

1. Open chrome://extensions/ → BrowserBridge → Details → Extension options.
2. Click Generate to create a secure auth token, then Save.
3. Expand Set up your MCP client, review the live JSON, and click Copy configuration.
4. Paste it into your MCP client config. See the MCP local server setup guide.
5. Restart your MCP client.

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json Linux: ~/.config/Claude/claude_desktop_config.json

The copied configuration uses NPX after this package is published as @wpscholar/browser-bridge:

{
  "mcpServers": {
    "browser-bridge": {
      "command": "npx",
      "args": ["--yes", "@wpscholar/browser-bridge"],
      "env": {
        "BROWSER_BRIDGE_CHROME_PORT": "58080",
        "BROWSER_BRIDGE_AUTH_TOKEN": "replace-with-a-long-random-secret"
      }
    }
  }
}

If you change the Options-page port or token, the JSON preview updates immediately. Copy again and restart your MCP client so both sides stay in sync.

Important Notes:

• Requires Node.js 24+ on the machine running the MCP client
• Do NOT run host.js when using Claude Desktop — the NPX/mcp-stdio.js entry point starts the Chrome extension WebSocket server automatically
• If you get a "port already in use" error, make sure host.js is not running
• Make sure the Chrome extension is loaded in Chrome
• Restart your MCP client after updating the configuration
• Copied configuration includes a secret; do not share screenshots of it or commit it

Local development without NPX

While developing from a git checkout before the package is published, point Claude Desktop at the local stdio entry point instead:

{
  "mcpServers": {
    "browser-bridge": {
      "command": "node",
      "args": ["/absolute/path/to/server/mcp-stdio.js"],
      "env": {
        "BROWSER_BRIDGE_CHROME_PORT": "58080",
        "BROWSER_BRIDGE_AUTH_TOKEN": "replace-with-a-long-random-secret"
      }
    }
  }
}

Example path (adjust for your system):

• macOS/Linux: /Users/yourusername/Sites/browser-bridge/server/mcp-stdio.js
• Windows: C:\\Users\\YourUsername\\Sites\\browser-bridge\\server\\mcp-stdio.js

Other MCP Clients (HTTP-based)

Any MCP client that supports HTTP/SSE transport can connect to:

• URL: http://127.0.0.1:6001/mcp
• Transport: Streamable HTTP (SSE)
• Authentication: Authorization: Bearer <token>

For HTTP clients, start the server with:

BROWSER_BRIDGE_AUTH_TOKEN=replace-with-a-long-random-secret npm start

This starts both the Chrome extension server (port 58080) and MCP HTTP server (port 6001). HTTP clients must send BROWSER_BRIDGE_AUTH_TOKEN as their bearer token.

Development

Project Structure

browser-bridge/
├── extension/              # Chrome extension files
│   ├── manifest.json      # Extension manifest
│   ├── background.js      # Service worker
│   ├── config.js          # Static fallback port + auth token + npm package name
│   ├── options.html       # Per-profile options, token generator, MCP setup UI
│   ├── options.js         # Options page logic (chrome.storage.local)
│   └── icons/             # Extension icons
├── server/                # Server (WebSocket + MCP server)
│   ├── host.js           # HTTP server for extension + MCP (HTTP mode)
│   ├── mcp-stdio.js      # Entry point for Claude Desktop (stdio mode)
│   ├── mcp-server.js     # MCP server implementation
│   ├── config.js         # Shared port configuration/constants
│   ├── chrome-bridge.js  # Authenticated WebSocket bridge to the extension
│   ├── tools/            # Tool implementations
│   │   ├── tabs.js
│   │   ├── bookmarks.js
│   │   ├── history.js
│   │   ├── tabGroups.js
│   │   ├── windows.js
│   │   ├── sessions.js
│   │   ├── topSites.js
│   │   ├── downloads.js
│   │   ├── webNavigation.js
│   │   ├── action.js
│   │   ├── scripting.js
│   │   ├── capture.js
│   │   └── notifications.js
└── package.json          # Root package.json (dependencies and scripts)

Testing

For HTTP-based MCP clients:

1. Load the extension in Chrome (Developer mode)
2. Start the server: BROWSER_BRIDGE_AUTH_TOKEN=replace-with-a-long-random-secret npm start
3. Connect an MCP client to http://127.0.0.1:6001/mcp
4. Test tool calls through the MCP client

For Claude Desktop (stdio-based):

1. Load the extension in Chrome (Developer mode)
2. Configure Claude Desktop from the Options-page setup JSON (or a local mcp-stdio.js path)
3. Restart Claude Desktop
4. The server will start automatically when Claude Desktop connects
5. Test tool calls through Claude Desktop

Debugging

• Check Chrome extension background service worker logs in chrome://extensions/
• Server logs are written to stderr (will appear in terminal)
• MCP server logs are written to stderr
• Verify the extension WebSocket connection by checking network requests in Chrome DevTools (look for /chrome/ws)
• For Claude Desktop, check that mcp-stdio.js path is correct and executable

Enable extension bridge tracing

The extension keeps routine WebSocket, authentication, keep-alive, and Chrome API request/response logs off by default. To trace that flow:

1. Go to chrome://extensions/ → BrowserBridge → Details → Extension options.
2. Expand Advanced settings, enable debug logging, and click Save.
3. Open the BrowserBridge service worker console from the extension's details page, then reproduce the issue.
4. Disable the setting and save when finished.

Errors, authentication failures, and failed Chrome API calls are always logged, even when debug tracing is disabled.

Security Considerations

• The extension requests browser-management permissions plus scripting and <all_urls> to support page interaction on tabs the user has already opened.
• All Chrome API calls are validated
• The servers run on localhost only (127.0.0.1)
• The WebSocket bridge and HTTP MCP endpoint require authentication tokens.
• The HTTP MCP endpoint does not configure CORS; it is bound to localhost.
• Page text, HTML, form values (including password fields), and screenshots can be returned to the connected MCP client. Treat page content as untrusted: malicious pages can contain prompt-injection instructions. The MCP client and its AI model handle returned data under their own policies.

Troubleshooting

Extension not connecting to server

1. Verify the server is running with a non-empty BROWSER_BRIDGE_AUTH_TOKEN
2. Check that port 58080 is not in use by another process
3. Check Chrome extension background service worker logs for connection errors
4. If using a custom port, set the matching port and auth token on the extension Options page. For a single profile, you can instead update the static fallback values in extension/config.js and reload the unpacked extension.

MCP server not starting

1. Ensure Node.js 24+ is installed
2. Check that all dependencies are installed: npm install
3. Verify ports 58080 and 6001 (or your configured ports) are not in use
4. Check stderr for error messages

Claude Desktop not connecting

1. Verify the path to mcp-stdio.js is absolute and correct when using a source checkout
2. Check that Node.js is in your PATH
3. Verify the file is executable (Unix/Linux/macOS): chmod +x server/mcp-stdio.js
4. Check Claude Desktop logs for connection errors
5. Ensure the Chrome extension is loaded and the server (port 58080) is running

Tools not working

1. Verify the extension has the necessary permissions
2. Check the background service worker for errors
3. Ensure the server is running
4. For HTTP clients: Verify MCP client is connected to http://127.0.0.1:6001/mcp and sends its configured bearer token
5. For Claude Desktop: Check that the stdio server started successfully

License

MIT

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.