Firefox Browser Bridge

Note: This entire project — all code, tests, documentation, and configuration — was generated by Claude (Anthropic). No human-written code.

MCP server + Firefox extension that gives Claude Code real-time browser debugging tools.

What It Does

Connects Firefox to Claude Code via the Model Context Protocol, enabling Claude to inspect network traffic, query the DOM, read console logs, and capture WebSocket frames -- all from the CLI.

Available Tools

Network

Page

Console

WebSocket

Related MCP server: gotham-browser

Architecture

Claude Code <── MCP stdio ──> Python Server <── WebSocket ──> Firefox Extension
                               (port 7865)

The system has two components:

1. Python MCP Server (src/mcp_server/) -- runs two async tasks: an MCP stdio server that exposes tools to Claude Code, and a WebSocket server on port 7865 that communicates with the extension.

2. Firefox Extension (extension/) -- a Manifest V2 background script that connects as a WebSocket client to the MCP server. It captures HTTP traffic passively via the webRequest API, with page-level XHR/fetch hooking as a fallback for response bodies that filterResponseData fails to capture (common with POST responses on servers that use connection: close). It performs DOM queries, console log capture, and WebSocket frame interception on demand by injecting content scripts.

Data flow: Claude calls an MCP tool, the server either queries its local in-memory stores (for network data) or sends a command to the extension via WebSocket (for DOM, console, and WS operations). The extension executes the command and responds. Request/response correlation uses UUID-based message IDs with a 5-second timeout.

Prerequisites

• Python >= 3.12

• uv (Python package manager)

• Firefox >= 109

Quick Start

1. Clone the repository

git clone <repo-url>
cd firefox-extension

2. Install dependencies

uv sync

3. Load the Firefox extension

1. Open Firefox and navigate to about:debugging#/runtime/this-firefox

2. Click Load Temporary Add-on...

3. Select extension/manifest.json from the cloned repository

4. The extension badge shows ON (green) when connected to the MCP server, OFF (red) when disconnected

4. Configure MCP in your project

Add a .mcp.json file to your project root (or merge into an existing one):

{
  "mcpServers": {
    "browser-bridge": {
      "command": "uv",
      "args": ["run", "--directory", "/absolute/path/to/firefox-extension", "python", "-m", "mcp_server.server"]
    }
  }
}

Replace /absolute/path/to/firefox-extension with the actual path to the cloned repository.

5. Restart Claude Code

The MCP tools appear automatically. You can verify by asking Claude to list its available tools.

Extension Controls

Click the extension icon in the Firefox toolbar to open the control panel. From here you can:

• See the connection status (green dot = connected to MCP server, red = disconnected)

• Toggle individual capabilities on or off:

When a capability is disabled, the corresponding MCP tools return a "capability disabled" error. Settings persist across browser restarts via browser.storage.local.

This is useful for limiting the amount of data flowing through the bridge -- for example, disable network capture when you only need DOM queries, or turn off everything except WebSocket frames during a targeted debugging session.

Usage Examples

Once everything is connected, you can ask Claude Code things like:

• "Check the network requests for any failed API calls on this page"

• "Query the DOM for all form input elements"

• "Start capturing WebSocket frames for wss://api.example.com and show me what comes through"

• "Show me the console errors from the current page"

• "Search the captured network traffic for any requests containing 'auth'"

• "Get the full response body of that 500 error request"

Tool Reference

get_network_requests

List captured HTTP requests, newest first.

get_request_details

Get full details of a specific request.

search_network

Full-text search across captured request URLs, headers, and bodies.

get_page_info

Get the active tab's URL, title, and tab ID. No parameters.

query_dom

Query DOM elements by CSS selector.

get_page_html

Get full page HTML or a specific element's HTML.

get_console_logs

Get recent console log entries from the current page.

start_ws_capture

Start capturing WebSocket frames for connections matching a URL pattern. Frames are not captured by default -- you must call this first.

stop_ws_capture

Stop capturing WebSocket frames.

get_ws_frames

Retrieve captured WebSocket frames.

How It Works

The MCP server (src/mcp_server/server.py) launches two concurrent async tasks:

• MCP stdio server -- communicates with Claude Code over stdin/stdout using the MCP protocol. Exposes 10 tools.

• WebSocket server -- listens on ws://127.0.0.1:7865 for the Firefox extension to connect.

The Firefox extension runs a persistent background script that:

• Connects as a WebSocket client and auto-reconnects with exponential backoff on disconnection.

• Passively captures all HTTP traffic using Firefox's webRequest API (listeners are registered dynamically and only active when network capture is enabled). Response bodies are captured via filterResponseData (primary) with two fallback mechanisms: cache-based re-fetch for GET requests, and page-level XHR/fetch hooking via dynamically registered content script (document_start) for POST/PUT/DELETE/PATCH responses where filterResponseData produces no data. Body capture (filterResponseData) is restricted to xmlhttprequest resource types (XHR/fetch API calls) -- document loads, scripts, stylesheets, images, fonts, and other non-API traffic skip body capture entirely, which dramatically reduces IPC overhead when monitoring all tabs. The hook communicates with the content script relay via synchronous DOM attribute + dispatchEvent, avoiding async postMessage races with page navigation. URLs are resolved to absolute before correlation. Captured data is stored in in-memory ring buffers -- 500 requests per tab, up to 20 tabs.

• On demand, injects content scripts into the active tab to perform DOM queries, console log interception, and WebSocket frame capture.

• Correlates requests and responses using UUID-based message IDs with asyncio Futures (5-second timeout on the server side).

Only a single extension connection is allowed at a time.

Key Files

Troubleshooting

Extension badge shows "OFF" The MCP server is not running. Start it manually to verify:

uv run python -m mcp_server.server

Tools return timeout errors The extension may have disconnected. Check the Firefox browser console (Ctrl+Shift+J) for WebSocket connection errors. Reload the extension from about:debugging.

No network data appears Make sure the extension is loaded and the badge shows "ON". Check that the Network Requests toggle is enabled in the extension popup. Network capture begins automatically when the extension connects -- navigate to a page or refresh to generate traffic.

DOM queries fail on certain pages Content script injection is blocked on privileged pages (about:*, moz-extension:*, and other restricted URLs). This is a Firefox security restriction.

Console logs are empty on first call Console log capture requires a content script injection, which happens on the first get_console_logs call. Logs generated before that first call are not captured. Call the tool once, reproduce the console output, then call it again.

POST response bodies are missing on pages with strict CSP The XHR/fetch hook fallback injects an inline <script> tag into the page. Pages with a strict Content-Security-Policy that blocks inline scripts (script-src without 'unsafe-inline') will prevent the hook from running. In that case, POST response bodies may be missing if Firefox's filterResponseData also fails (common with servers that send connection: close + gzip). GET responses are unaffected as they use a separate cache-based fallback.

Response bodies show garbled text This can happen if the response uses brotli (br) content-encoding and Firefox's filterResponseData delivers raw compressed bytes instead of decompressed data. This is rare in practice. The XHR/fetch hook handles JSON, XML (responseType: "document"), and plain text responses correctly; binary formats (arraybuffer, blob) are skipped.

Security Notes

• The WebSocket server binds to 127.0.0.1 only -- not accessible from the network.

• No data is persisted to disk. All captured data lives in memory and is lost when the server stops.

• The extension requires broad permissions (<all_urls>, webRequest, webRequestBlocking, tabs, storage) to capture network traffic across all sites. This is inherent to the functionality. However, all webRequest listeners and the XHR/fetch content script are only active when the corresponding capability is enabled — when disabled, the extension has near-zero overhead.

• Use the extension popup toggles to limit data exposure -- disable capabilities you don't need.

• The extension is loaded as a temporary add-on and must be re-loaded after each Firefox restart.

License

MIT