{"id":48443724,"url":"https://github.com/mozilla/firefox-devtools-mcp","last_synced_at":"2026-04-19T13:06:47.752Z","repository":{"id":318824980,"uuid":"1072399993","full_name":"mozilla/firefox-devtools-mcp","owner":"mozilla","description":"Model Context Protocol server for Firefox DevTools - enables AI assistants to inspect and control Firefox browser through the Remote Debugging Protocol","archived":false,"fork":false,"pushed_at":"2026-04-03T08:37:04.000Z","size":869,"stargazers_count":94,"open_issues_count":1,"forks_count":21,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-04-04T21:52:42.880Z","etag":null,"topics":["claude-code","firefox","mcp","mcp-server"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":false,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mozilla.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-10-08T17:04:40.000Z","updated_at":"2026-04-04T16:37:55.000Z","dependencies_parsed_at":"2025-10-16T12:23:56.801Z","dependency_job_id":"b8430dba-b955-4d76-a6e1-67de78c022db","html_url":"https://github.com/mozilla/firefox-devtools-mcp","commit_stats":null,"previous_names":["freema/firefox-devtools-mcp","mozilla/firefox-devtools-mcp"],"tags_count":24,"template":false,"template_full_name":null,"purl":"pkg:github/mozilla/firefox-devtools-mcp","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mozilla%2Ffirefox-devtools-mcp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mozilla%2Ffirefox-devtools-mcp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mozilla%2Ffirefox-devtools-mcp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mozilla%2Ffirefox-devtools-mcp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mozilla","download_url":"https://codeload.github.com/mozilla/firefox-devtools-mcp/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mozilla%2Ffirefox-devtools-mcp/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31580507,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-08T14:31:17.711Z","status":"ssl_error","status_checked_at":"2026-04-08T14:31:17.202Z","response_time":54,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["claude-code","firefox","mcp","mcp-server"],"created_at":"2026-04-06T17:00:21.419Z","updated_at":"2026-04-09T01:01:12.668Z","avatar_url":"https://github.com/mozilla.png","language":"TypeScript","funding_links":[],"categories":["Browser Automation"],"sub_categories":["DevTools"],"readme":"# Firefox DevTools MCP\n\n[![npm version](https://badge.fury.io/js/firefox-devtools-mcp.svg)](https://www.npmjs.com/package/firefox-devtools-mcp)\n[![CI](https://github.com/mozilla/firefox-devtools-mcp/workflows/CI/badge.svg)](https://github.com/mozilla/firefox-devtools-mcp/actions/workflows/ci.yml)\n[![codecov](https://codecov.io/gh/mozilla/firefox-devtools-mcp/branch/main/graph/badge.svg)](https://codecov.io/gh/mozilla/firefox-devtools-mcp)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n\n\u003ca href=\"https://glama.ai/mcp/servers/@mozilla/firefox-devtools-mcp\"\u003e\u003cimg src=\"https://glama.ai/mcp/servers/@mozilla/firefox-devtools-mcp/badge\" height=\"223\" alt=\"Glama\"\u003e\u003c/a\u003e\n\nModel Context Protocol server for automating Firefox via WebDriver BiDi (through Selenium WebDriver). Works with Claude Code, Claude Desktop, Cursor, Cline and other MCP clients.\n\nRepository: https://github.com/mozilla/firefox-devtools-mcp\n\n\u003e **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.\n\n## Requirements\n\n- Node.js ≥ 20.19.0\n- Firefox 100+ installed (auto‑detected, or pass `--firefox-path`)\n\n## Install and use with Claude Code (npx)\n\nRecommended: use npx so you always run the latest published version from npm.\n\nOption A — Claude Code CLI\n\n```bash\nclaude mcp add firefox-devtools npx firefox-devtools-mcp@latest\n```\n\nPass options either as args or env vars. Examples:\n\n```bash\n# Headless + viewport via args\nclaude mcp add firefox-devtools npx firefox-devtools-mcp@latest -- --headless --viewport 1280x720\n\n# Or via environment variables\nclaude mcp add firefox-devtools npx firefox-devtools-mcp@latest \\\n  --env START_URL=https://example.com \\\n  --env FIREFOX_HEADLESS=true\n```\n\nOption B — Edit Claude Code settings JSON\n\nAdd to your Claude Code config file:\n\n- macOS: `~/Library/Application Support/Claude/Code/mcp_settings.json`\n- Linux: `~/.config/claude/code/mcp_settings.json`\n- Windows: `%APPDATA%\\Claude\\Code\\mcp_settings.json`\n\n```json\n{\n  \"mcpServers\": {\n    \"firefox-devtools\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"firefox-devtools-mcp@latest\", \"--headless\", \"--viewport\", \"1280x720\"],\n      \"env\": {\n        \"START_URL\": \"about:home\"\n      }\n    }\n  }\n}\n```\n\nOption C — Helper script (local dev build)\n\n```bash\nnpm run setup\n# Choose Claude Code; the script saves JSON to the right path\n```\n\n## Try it with MCP Inspector\n\n```bash\nnpx @modelcontextprotocol/inspector npx firefox-devtools-mcp@latest --start-url https://example.com --headless\n```\n\nThen call tools like:\n\n- `list_pages`, `select_page`, `navigate_page`\n- `take_snapshot` then `click_by_uid` / `fill_by_uid`\n- `list_network_requests` (always‑on capture), `get_network_request`\n- `screenshot_page`, `list_console_messages`\n\n## CLI options\n\nYou can pass flags or environment variables (names on the right):\n\n- `--firefox-path` — absolute path to Firefox binary\n- `--headless` — run without UI (`FIREFOX_HEADLESS=true`)\n- `--viewport 1280x720` — initial window size\n- `--profile-path` — use a specific Firefox profile\n- `--firefox-arg` — extra Firefox arguments (repeatable)\n- `--start-url` — open this URL on start (`START_URL`)\n- `--accept-insecure-certs` — ignore TLS errors (`ACCEPT_INSECURE_CERTS=true`)\n- `--connect-existing` — attach to an already-running Firefox instead of launching a new one (`CONNECT_EXISTING=true`)\n- `--marionette-port` — Marionette port for connect-existing mode, default 2828 (`MARIONETTE_PORT`)\n- `--pref name=value` — set Firefox preference at startup via `moz:firefoxOptions` (repeatable)\n- `--enable-script` — enable the `evaluate_script` tool, which executes arbitrary JavaScript in the page context (`ENABLE_SCRIPT=true`)\n- `--enable-privileged-context` — enable privileged context tools: list/select privileged contexts, evaluate privileged scripts, get/set Firefox prefs, and list extensions. Requires `MOZ_REMOTE_ALLOW_SYSTEM_ACCESS=1` (`ENABLE_PRIVILEGED_CONTEXT=true`)\n\n\u003e **Note on `--pref`:** When Firefox runs in automation, it applies [RecommendedPreferences](https://searchfox.org/firefox-main/source/remote/shared/RecommendedPreferences.sys.mjs) that modify browser behavior for testing. The `--pref` option allows overriding these defaults when needed.\n\n### Connect to existing Firefox\n\nUse `--connect-existing` to automate your real browsing session — with cookies, logins, and open tabs intact:\n\n```bash\n# Start Firefox with Marionette enabled\nfirefox --marionette\n\n# Run the MCP server\nnpx firefox-devtools-mcp --connect-existing --marionette-port 2828\n```\n\nOr set `marionette.enabled` to `true` in `about:config` (or `user.js`) to enable Marionette on every launch.\n\nBiDi-dependent features (console events, network events) are not available in connect-existing mode; all other features work normally.\n\n\u003e **Warning:** Do not leave Marionette enabled during normal browsing. It sets\n\u003e `navigator.webdriver = true` and changes other browser fingerprint signals,\n\u003e which can trigger bot detection on sites protected by Cloudflare, Akamai, etc.\n\u003e Only enable Marionette when you need MCP automation, then restart Firefox\n\u003e normally afterward.\n\n## Tool overview\n\n- Pages: list/new/navigate/select/close\n- Snapshot/UID: take/resolve/clear\n- Input: click/hover/fill/drag/upload/form fill\n- Network: list/get (ID‑first, filters, always‑on capture)\n- Console: list/clear\n- Screenshot: page/by uid (with optional `saveTo` for CLI environments)\n- Script: evaluate_script\n- Privileged Context: list/select privileged (\"chrome\") contexts, evaluate_privileged_script (requires `MOZ_REMOTE_ALLOW_SYSTEM_ACCESS=1`)\n- WebExtension: install_extension, uninstall_extension, list_extensions (list requires `MOZ_REMOTE_ALLOW_SYSTEM_ACCESS=1`)\n- Firefox Management: get_firefox_info, get_firefox_output, restart_firefox, set_firefox_prefs, get_firefox_prefs\n- Utilities: accept/dismiss dialog, history back/forward, set viewport\n\n### Screenshot optimization for Claude Code\n\nWhen using screenshots in Claude Code CLI, the base64 image data can consume significant context.\nUse the `saveTo` parameter to save screenshots to disk instead:\n\n```\nscreenshot_page({ saveTo: \"/tmp/page.png\" })\nscreenshot_by_uid({ uid: \"abc123\", saveTo: \"/tmp/element.png\" })\n```\n\nThe file can then be viewed with Claude Code's `Read` tool without impacting context size.\n\n## Local development\n\n```bash\nnpm install\nnpm run build\n\n# Run with Inspector against local build\nnpx @modelcontextprotocol/inspector node dist/index.js --headless --viewport 1280x720\n\n# Or run in dev with hot reload\nnpm run inspector:dev\n```\n\n## Testing\n\n```bash\nnpm run test:run          # all tests once (unit + integration)\nnpm test                  # watch mode\n```\n\nSee [docs/testing.md](docs/testing.md) for full details on running specific test suites, the e2e scenario coverage, and known issues.\n\n## Troubleshooting\n\n- Firefox not found: pass `--firefox-path \"/Applications/Firefox.app/Contents/MacOS/firefox\"` (macOS) or the correct path on your OS.\n- First run is slow: Selenium sets up the BiDi session; subsequent runs are faster.\n- Stale UIDs after navigation: take a fresh snapshot (`take_snapshot`) before using UID tools.\n- Windows 10: Error during discovery for MCP server 'firefox-devtools': MCP error -32000: Connection closed\n  - **Solution 1** Call using `cmd` (For more info https://github.com/modelcontextprotocol/servers/issues/1082#issuecomment-2791786310)\n\n    ```json\n    \"mcpServers\": {\n      \"firefox-devtools\": {\n        \"command\": \"cmd\",\n        \"args\": [\"/c\", \"npx\", \"-y\", \"firefox-devtools-mcp@latest\"]\n      }\n    }\n    ```\n\n    \u003e **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.\n\n  - **Solution 2** Instead of another layer of shell you can write the absolute path to `npx`:\n\n    ```json\n    \"mcpServers\": {\n      \"firefox-devtools\": {\n        \"command\": \"C:\\\\nvm4w\\\\nodejs\\\\npx.ps1\",\n        \"args\": [\"-y\", \"firefox-devtools-mcp@latest\"]\n      }\n    }\n    ```\n\n    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.\n\n## Versioning\n\n- Pre‑1.0 API: versions start at `0.x`. Use `@latest` with npx for the newest release.\n\n## CI and Release\n\n- GitHub Actions for CI, Release, and npm publish are included. See docs/ci-and-release.md for details and required secrets.\n\n## Issues and Contributing\n\nIssues are tracked on [Bugzilla](https://bugzilla.mozilla.org) under **product: Developer Infrastructure**, **component: AI for Development**.\n\n- [File a new issue](https://bugzilla.mozilla.org/enter_bug.cgi?format=__default__\u0026blocked=2026717\u0026product=Developer%20Infrastructure\u0026component=AI%20for%20Development)\n- [Meta bug (tracks all firefox-devtools-mcp issues)](https://bugzilla.mozilla.org/show_bug.cgi?id=2026717)\n\nFor questions and discussion, join the [#firefox-devtools-mcp Matrix room](https://chat.mozilla.org/#/room/#firefox-devtools-mcp:mozilla.org).\n\n## Author\n\nMaintained by [Mozilla](https://www.mozilla.org).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmozilla%2Ffirefox-devtools-mcp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmozilla%2Ffirefox-devtools-mcp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmozilla%2Ffirefox-devtools-mcp/lists"}