Firefox DevTools MCP

1# Firefox DevTools MCP
2 
3[![npm version](https://badge.fury.io/js/firefox-devtools-mcp.svg)](https://www.npmjs.com/package/firefox-devtools-mcp)
4[![CI](https://github.com/freema/firefox-devtools-mcp/workflows/CI/badge.svg)](https://github.com/freema/firefox-devtools-mcp/actions/workflows/ci.yml)
5[![codecov](https://codecov.io/gh/freema/firefox-devtools-mcp/branch/main/graph/badge.svg)](https://codecov.io/gh/freema/firefox-devtools-mcp)
6[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
7 
8<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>
9 
10Model Context Protocol server for automating Firefox via WebDriver BiDi (through Selenium WebDriver). Works with Claude Code, Claude Desktop, Cursor, Cline and other MCP clients.
11 
12Repository: https://github.com/freema/firefox-devtools-mcp
13 
14> **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.
15 
16## Requirements
17 
18- Node.js ≥ 20.19.0
19- Firefox 100+ installed (auto‑detected, or pass `--firefox-path`)
20 
21## Install and use with Claude Code (npx)
22 
23Recommended: use npx so you always run the latest published version from npm.
24 
25Option A — Claude Code CLI
26 
27```bash
28claude mcp add firefox-devtools npx firefox-devtools-mcp@latest
29```
30 
31Pass options either as args or env vars. Examples:
32 
33```bash
34# Headless + viewport via args
35claude mcp add firefox-devtools npx firefox-devtools-mcp@latest -- --headless --viewport 1280x720
36 
37# Or via environment variables
38claude mcp add firefox-devtools npx firefox-devtools-mcp@latest \
39  --env START_URL=https://example.com \
40  --env FIREFOX_HEADLESS=true
41```
42 
43Option B — Edit Claude Code settings JSON
44 
45Add to your Claude Code config file:
46- macOS: `~/Library/Application Support/Claude/Code/mcp_settings.json`
47- Linux: `~/.config/claude/code/mcp_settings.json`
48- Windows: `%APPDATA%\Claude\Code\mcp_settings.json`
49 
50```json
51{
52  "mcpServers": {
53    "firefox-devtools": {
54      "command": "npx",
55      "args": ["-y", "firefox-devtools-mcp@latest", "--headless", "--viewport", "1280x720"],
56      "env": {
57        "START_URL": "about:home"
58      }
59    }
60  }
61}
62```
63 
64Option C — Helper script (local dev build)
65 
66```bash
67npm run setup
68# Choose Claude Code; the script saves JSON to the right path
69```
70 
71## Try it with MCP Inspector
72 
73```bash
74npx @modelcontextprotocol/inspector npx firefox-devtools-mcp@latest --start-url https://example.com --headless
75```
76 
77Then call tools like:
78- `list_pages`, `select_page`, `navigate_page`
79- `take_snapshot` then `click_by_uid` / `fill_by_uid`
80- `list_network_requests` (always‑on capture), `get_network_request`
81- `screenshot_page`, `list_console_messages`
82 
83## CLI options
84 
85You can pass flags or environment variables (names on the right):
86 
87- `--firefox-path` — absolute path to Firefox binary
88- `--headless` — run without UI (`FIREFOX_HEADLESS=true`)
89- `--viewport 1280x720` — initial window size
90- `--profile-path` — use a specific Firefox profile
91- `--firefox-arg` — extra Firefox arguments (repeatable)
92- `--start-url` — open this URL on start (`START_URL`)
93- `--accept-insecure-certs` — ignore TLS errors (`ACCEPT_INSECURE_CERTS=true`)
94 
95## Tool overview
96 
97- Pages: list/new/navigate/select/close
98- Snapshot/UID: take/resolve/clear
99- Input: click/hover/fill/drag/upload/form fill
100- Network: list/get (ID‑first, filters, always‑on capture)
101- Console: list/clear
102- Screenshot: page/by uid (with optional `saveTo` for CLI environments)
103- Utilities: accept/dismiss dialog, history back/forward, set viewport
104 
105### Screenshot optimization for Claude Code
106 
107When using screenshots in Claude Code CLI, the base64 image data can consume significant context.
108Use the `saveTo` parameter to save screenshots to disk instead:
109 
110```
111screenshot_page({ saveTo: "/tmp/page.png" })
112screenshot_by_uid({ uid: "abc123", saveTo: "/tmp/element.png" })
113```
114 
115The file can then be viewed with Claude Code's `Read` tool without impacting context size.
116 
117## Local development
118 
119```bash
120npm install
121npm run build
122 
123# Run with Inspector against local build
124npx @modelcontextprotocol/inspector node dist/index.js --headless --viewport 1280x720
125 
126# Or run in dev with hot reload
127npm run inspector:dev
128```
129 
130## Troubleshooting
131 
132- Firefox not found: pass `--firefox-path "/Applications/Firefox.app/Contents/MacOS/firefox"` (macOS) or the correct path on your OS.
133- First run is slow: Selenium sets up the BiDi session; subsequent runs are faster.
134- Stale UIDs after navigation: take a fresh snapshot (`take_snapshot`) before using UID tools.
135 
136## Versioning
137 
138- Pre‑1.0 API: versions start at `0.x`. Use `@latest` with npx for the newest release.
139 
140## CI and Release
141 
142- GitHub Actions for CI, Release, and npm publish are included. See docs/ci-and-release.md for details and required secrets.
143 
144## Author
145 
146Created by [Tomáš Grasl](https://www.tomasgrasl.cz/)
147