Metadata-Version: 2.4
Name: firefox-browser-mcp
Version: 0.2.0
Summary: MCP server that controls Firefox through a companion WebExtension over a WebSocket bridge.
Project-URL: Homepage, https://github.com/ICWR-TEAM/Firefox-Browser-MCP
Project-URL: Repository, https://github.com/ICWR-TEAM/Firefox-Browser-MCP
Project-URL: Issues, https://github.com/ICWR-TEAM/Firefox-Browser-MCP/issues
Author: ICWR-TEAM
License: MIT
Keywords: automation,browser,firefox,llm,mcp,model-context-protocol
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Internet :: WWW/HTTP :: Browsers
Classifier: Topic :: Software Development :: Testing
Requires-Python: >=3.10
Requires-Dist: mcp<2.0.0,>=1.2.0
Requires-Dist: websockets>=12.0
Description-Content-Type: text/markdown

# Firefox Browser MCP — Server

An [MCP](https://modelcontextprotocol.io) 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

```bash
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):

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

| Flag          | Default     | Env fallback      |
| ------------- | ----------- | ----------------- |
| `--host`      | `127.0.0.1` | `FBMCP_HOST`      |
| `--port`      | `9010`      | `FBMCP_PORT`      |
| `--log-level` | `INFO`      | `FBMCP_LOG_LEVEL` |

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

## Configure your MCP client

```json
{
  "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:

| `tab` value            | Meaning                                   |
| ---------------------- | ----------------------------------------- |
| omitted                | the currently active tab                  |
| `123` / `"123"`        | the tab whose id is 123                   |
| `"github.com"`         | first tab whose **url** contains it       |
| `"Inbox"`              | first tab whose **title** contains it     |

## Environment variables

| Variable          | Default     | Description               |
| ----------------- | ----------- | ------------------------- |
| `FBMCP_HOST`      | `127.0.0.1` | WebSocket bridge host     |
| `FBMCP_PORT`      | `9010`      | WebSocket bridge port     |
| `FBMCP_LOG_LEVEL` | `INFO`      | Python logging level      |

> 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

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