firefox-devtools-mcp

# Firefox DevTools MCP [](https://www.npmjs.com/package/firefox-devtools-mcp) [](https://github.com/freema/firefox-devtools-mcp/actions/workflows/ci.yml) [](https://codecov.io/gh/freema/firefox-devtools-mcp) [](https://opensource.org/licenses/MIT) <a href="https://glama.ai/mcp/servers/@freema/firefox-devtools-mcp"><img src="https://glama.ai/mcp/servers/@freema/firefox-devtools-mcp/badge" height="223" alt="Glama"></a> Model Context Protocol server for automating Firefox via WebDriver BiDi (through Selenium WebDriver). Works with Claude Code, Claude Desktop, Cursor, Cline and other MCP clients. Repository: https://github.com/freema/firefox-devtools-mcp > **Note**: This MCP server requires a local Firefox browser installation and cannot run on cloud hosting services like glama.ai. Use `npx firefox-devtools-mcp@latest` to run locally, or use Docker with the provided Dockerfile. ## Requirements - Node.js ≥ 20.19.0 - Firefox 100+ installed (auto‑detected, or pass `--firefox-path`) ## Install and use with Claude Code (npx) Recommended: use npx so you always run the latest published version from npm. Option A — Claude Code CLI ```bash claude mcp add firefox-devtools npx firefox-devtools-mcp@latest ``` Pass options either as args or env vars. Examples: ```bash # Headless + viewport via args claude mcp add firefox-devtools npx firefox-devtools-mcp@latest -- --headless --viewport 1280x720 # Or via environment variables claude mcp add firefox-devtools npx firefox-devtools-mcp@latest \ --env START_URL=https://example.com \ --env FIREFOX_HEADLESS=true ``` Option B — Edit Claude Code settings JSON Add to your Claude Code config file: - macOS: `~/Library/Application Support/Claude/Code/mcp_settings.json` - Linux: `~/.config/claude/code/mcp_settings.json` - Windows: `%APPDATA%\Claude\Code\mcp_settings.json` ```json { "mcpServers": { "firefox-devtools": { "command": "npx", "args": ["-y", "firefox-devtools-mcp@latest", "--headless", "--viewport", "1280x720"], "env": { "START_URL": "about:home" } } } } ``` Option C — Helper script (local dev build) ```bash npm run setup # Choose Claude Code; the script saves JSON to the right path ``` ## Try it with MCP Inspector ```bash npx @modelcontextprotocol/inspector npx firefox-devtools-mcp@latest --start-url https://example.com --headless ``` Then call tools like: - `list_pages`, `select_page`, `navigate_page` - `take_snapshot` then `click_by_uid` / `fill_by_uid` - `list_network_requests` (always‑on capture), `get_network_request` - `screenshot_page`, `list_console_messages` ## CLI options You can pass flags or environment variables (names on the right): - `--firefox-path` — absolute path to Firefox binary - `--headless` — run without UI (`FIREFOX_HEADLESS=true`) - `--viewport 1280x720` — initial window size - `--profile-path` — use a specific Firefox profile - `--firefox-arg` — extra Firefox arguments (repeatable) - `--start-url` — open this URL on start (`START_URL`) - `--accept-insecure-certs` — ignore TLS errors (`ACCEPT_INSECURE_CERTS=true`) - `--connect-existing` — attach to an already-running Firefox instead of launching a new one (`CONNECT_EXISTING=true`) - `--marionette-port` — Marionette port for connect-existing mode, default 2828 (`MARIONETTE_PORT`) ### Connect to existing Firefox Use `--connect-existing` to automate your real browsing session — with cookies, logins, and open tabs intact: ```bash # Start Firefox with Marionette enabled firefox --marionette # Run the MCP server npx firefox-devtools-mcp --connect-existing --marionette-port 2828 ``` Or set `marionette.enabled` to `true` in `about:config` (or `user.js`) to enable Marionette on every launch. BiDi-dependent features (console events, network events) are not available in connect-existing mode; all other features work normally. > **Warning:** Do not leave Marionette enabled during normal browsing. It sets > `navigator.webdriver = true` and changes other browser fingerprint signals, > which can trigger bot detection on sites protected by Cloudflare, Akamai, etc. > Only enable Marionette when you need MCP automation, then restart Firefox > normally afterward. ## Tool overview - Pages: list/new/navigate/select/close - Snapshot/UID: take/resolve/clear - Input: click/hover/fill/drag/upload/form fill - Network: list/get (ID‑first, filters, always‑on capture) - Console: list/clear - Screenshot: page/by uid (with optional `saveTo` for CLI environments) - Utilities: accept/dismiss dialog, history back/forward, set viewport ### Screenshot optimization for Claude Code When using screenshots in Claude Code CLI, the base64 image data can consume significant context. Use the `saveTo` parameter to save screenshots to disk instead: ``` screenshot_page({ saveTo: "/tmp/page.png" }) screenshot_by_uid({ uid: "abc123", saveTo: "/tmp/element.png" }) ``` The file can then be viewed with Claude Code's `Read` tool without impacting context size. ## Local development ```bash npm install npm run build # Run with Inspector against local build npx @modelcontextprotocol/inspector node dist/index.js --headless --viewport 1280x720 # Or run in dev with hot reload npm run inspector:dev ``` ## Troubleshooting - Firefox not found: pass `--firefox-path "/Applications/Firefox.app/Contents/MacOS/firefox"` (macOS) or the correct path on your OS. - First run is slow: Selenium sets up the BiDi session; subsequent runs are faster. - Stale UIDs after navigation: take a fresh snapshot (`take_snapshot`) before using UID tools. - Windows 10: Error during discovery for MCP server 'firefox-devtools': MCP error -32000: Connection closed - **Solution 1** Call using `cmd` (For more info https://github.com/modelcontextprotocol/servers/issues/1082#issuecomment-2791786310) ```json "mcpServers": { "firefox-devtools": { "command": "cmd", "args": ["/c", "npx", "-y", "firefox-devtools-mcp@latest"] } } ``` > **The Key Change:** On Windows, running a Node.js package via `npx` often requires the `cmd /c` prefix to be executed correctly from within another process like VSCode's extension host. Therefore, `"command": "npx"` was replaced with `"command": "cmd"`, and the actual `npx` command was moved into the `"args"` array, preceded by `"/c"`. This fix allows Windows to interpret the command correctly and launch the server. - **Solution 2** Instead of another layer of shell you can write the absolute path to `npx`: ```json "mcpServers": { "firefox-devtools": { "command": "C:\\nvm4w\\nodejs\\npx.ps1", "args": ["-y", "firefox-devtools-mcp@latest"] } } ``` Note: The path above is an example. You must adjust it to match the actual location of `npx` on your machine. Depending on your setup, the file extension might be `.cmd`, `.bat`, or `.exe` rather than `.ps1`. Also, ensure you use double backslashes (`\\`) as path delimiters, as required by the JSON format. ## Versioning - Pre‑1.0 API: versions start at `0.x`. Use `@latest` with npx for the newest release. ## CI and Release - GitHub Actions for CI, Release, and npm publish are included. See docs/ci-and-release.md for details and required secrets. ## Author Created by [Tomáš Grasl](https://www.tomasgrasl.cz/)