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

Tool	Description
get_network_requests	List captured HTTP requests, filterable by URL pattern, method, status code, and content type
get_request_details	Get full headers, request body, response body, and timing for a specific request
search_network	Full-text search across all captured request URLs, headers, and bodies

Page

Tool	Description
get_page_info	Get the active tab's URL, title, and tab ID
query_dom	Query DOM elements by CSS selector (returns tag, text, attributes, outerHTML)
get_page_html	Get full page HTML or a specific element's HTML (truncated at 500 KB)

Console

Tool	Description
get_console_logs	Get recent console log entries, filterable by level (log, warn, error, info, debug)

WebSocket

Tool	Description
start_ws_capture	Start capturing WebSocket frames matching a URL pattern
stop_ws_capture	Stop capturing WebSocket frames for a URL pattern
get_ws_frames	Retrieve captured frames, filterable by URL pattern and direction (sent/received)

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:

Toggle	Controls	MCP Tools Affected
Network Requests	HTTP traffic capture and storage	get_network_requests, get_request_details, search_network
DOM / HTML	Page queries and HTML access	get_page_info, query_dom, get_page_html
Console Logs	Console output capture	get_console_logs
WebSocket Frames	WS message interception	start_ws_capture, stop_ws_capture, get_ws_frames

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.

Parameter	Type	Required	Description
url_pattern	string	no	Regex pattern to match against URLs
method	string	no	HTTP method filter (GET, POST, etc.)
status_code	integer	no	HTTP status code filter
content_type	string	no	Content type substring filter (e.g. "json", "html")
limit	integer	no	Max results to return (default 50)

get_request_details

Get full details of a specific request.

Parameter	Type	Required	Description
request_id	string	yes	Request ID from get_network_requests

search_network

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

Parameter	Type	Required	Description
query	string	yes	Search string
limit	integer	no	Max results (default 50)

get_page_info

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

query_dom

Query DOM elements by CSS selector.

Parameter	Type	Required	Description
selector	string	yes	CSS selector to query

get_page_html

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

Parameter	Type	Required	Description
selector	string	no	CSS selector. If omitted, returns full page HTML

get_console_logs

Get recent console log entries from the current page.

Parameter	Type	Required	Description
level	string	no	Filter by level: log, warn, error, info, debug
limit	integer	no	Max entries (default 100)

start_ws_capture

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

Parameter	Type	Required	Description
url_pattern	string	yes	Pattern to match WebSocket connection URLs

stop_ws_capture

Stop capturing WebSocket frames.

Parameter	Type	Required	Description
url_pattern	string	yes	The same pattern passed to start_ws_capture

get_ws_frames

Retrieve captured WebSocket frames.

Parameter	Type	Required	Description
url_pattern	string	no	Filter by connection URL pattern
direction	string	no	Filter by direction: "sent" or "received"
limit	integer	no	Max frames (default 100)

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

File	Purpose
src/mcp_server/server.py	Entry point; wires up MCP + WebSocket servers
src/mcp_server/tools.py	MCP tool definitions and dispatch logic
src/mcp_server/ws_bridge.py	WebSocket server, connection manager, message routing
src/mcp_server/request_store.py	In-memory ring buffer stores for requests and WS frames
extension/background.js	All extension logic: WS client, network capture, DOM tools, WS frame capture
extension/xhr_hook_content.js	Content script for XHR/fetch response body capture (registered at document_start)

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