Firefox Browser MCP — Server

An MCP server that lets an LLM client drive a real Firefox browser — every tab, its DOM, arbitrary CSS selectors, and its network/API traffic. It talks to the companion firefox-extension/ WebExtension over a local WebSocket bridge.

MCP client (Claude Desktop, etc.)
        │  stdio (MCP)
        ▼
firefox-browser-mcp  ──ws://127.0.0.1:9010──►  Firefox extension  ──►  All tabs

Run with uvx

uvx --from ./mcp-server firefox-browser-mcp

Once published to PyPI: uvx firefox-browser-mcp.

CLI options

Connection settings can be passed as arguments (they override the FBMCP_* env vars):

uvx firefox-browser-mcp --host 127.0.0.1 --port 9010 --log-level INFO
uvx firefox-browser-mcp --version
uvx firefox-browser-mcp --help

The Firefox extension connects to this bridge; use the extension popup's Enable/Disable toggle to turn the connection on or off.

Transports (--transport)

• stdio (default) — the MCP client spawns one process per session, so the bridge lives only while a client session is open.

• sse / streamable-http — run the server once as an always-on HTTP service the client connects to by URL. The WebSocket bridge is tied to the HTTP server's lifetime, so it stays up across client sessions and the extension can stay connected continuously:

  uvx firefox-browser-mcp --transport sse --http-port 8000 --port 9010
  # MCP endpoint:  http://127.0.0.1:8000/sse   (streamable-http -> /mcp)
  

  Configure the client with a URL instead of a command:

  { "mcpServers": { "firefox-browser": { "url": "http://127.0.0.1:8000/sse" } } }
  

Configure your MCP client

{
  "mcpServers": {
    "firefox-browser": {
      "command": "uvx",
      "args": ["--from", "/absolute/path/to/mcp-server", "firefox-browser-mcp"]
    }
  }
}

Targeting tabs

Every tab has a stable numeric id (plus title and url). Get them with browser_list_tabs. Most tools accept an optional tab argument:

Environment variables

If you change the port, update the bridge URL in the extension popup.

Tools

Tabs — browser_list_tabs (id/title/url of every tab, all windows), browser_select_tab, browser_new_tab, browser_close_tab.

Navigation — browser_navigate, browser_go_back, browser_go_forward, browser_reload.

Inspection & extraction — browser_snapshot (accessibility tree with ref ids), browser_query (any CSS selector → refs, text, attributes, html), browser_get_text, browser_get_html, browser_get_attribute, browser_eval (run JS and return the result), browser_get_url, browser_screenshot, browser_get_console_logs.

Network / API — browser_get_network (captured requests with method, url, status, content-type, request & response bodies), browser_clear_network.

Interaction — browser_click, browser_type, browser_hover, browser_select_option, browser_press_key, browser_scroll, browser_wait. Interaction tools accept either a ref (from snapshot/query) or a CSS selector.

Status — browser_status.

Examples (what an agent can do)

• "List my tabs, then read the article in the tab with 'wikipedia' in its url": browser_list_tabs → browser_get_text(tab="wikipedia").
• "Grab all product prices": browser_query(selector=".price") or browser_eval(script="return Array.from(document.querySelectorAll('.price')).map(e=>e.textContent)").
• "Show the API calls this page made": browser_get_network(filter="xmlhttprequest") (includes JSON response bodies).
• "Log into the form": browser_type(selector="#email", text=...), browser_type(selector="#password", text=..., submit=True).

Development

cd mcp-server
uv venv && source .venv/bin/activate
uv pip install -e .
python -m firefox_browser_mcp.server