Firefox DevTools MCP

WebDriver BiDi（Selenium WebDriver 経由）を使用して Firefox を自動化するための Model Context Protocol サーバーです。Claude Code、Claude Desktop、Cursor、Cline などの MCP クライアントで動作します。

リポジトリ: https://github.com/mozilla/firefox-devtools-mcp

注: この MCP サーバーはローカルの Firefox ブラウザのインストールを必要とし、glama.ai のようなクラウドホスティングサービス上では実行できません。ローカルで実行するには npx firefox-devtools-mcp@latest を使用するか、提供されている Dockerfile を使用して Docker を利用してください。

要件

• Node.js ≥ 20.19.0

• Firefox 100 以上がインストールされていること（自動検出されます。または --firefox-path を渡してください）

Related MCP server: gecko-mcp

Claude Code でのインストールと使用 (npx)

npm から公開されている最新バージョンを常に実行できるように、npx の使用を推奨します。

オプション A — Claude Code CLI

claude mcp add firefox-devtools npx firefox-devtools-mcp@latest

オプションは引数または環境変数として渡します。例:

# 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

オプション B — Claude Code 設定 JSON の編集

Claude Code 設定ファイルに追加します:

• macOS: ~/Library/Application Support/Claude/Code/mcp_settings.json

• Linux: ~/.config/claude/code/mcp_settings.json

• Windows: %APPDATA%\Claude\Code\mcp_settings.json

{
  "mcpServers": {
    "firefox-devtools": {
      "command": "npx",
      "args": ["-y", "firefox-devtools-mcp@latest", "--headless", "--viewport", "1280x720"],
      "env": {
        "START_URL": "about:home"
      }
    }
  }
}

オプション C — ヘルパースクリプト (ローカル開発ビルド)

npm run setup
# Choose Claude Code; the script saves JSON to the right path

MCP Inspector で試す

npx @modelcontextprotocol/inspector npx firefox-devtools-mcp@latest --start-url https://example.com --headless

その後、以下のようなツールを呼び出します:

• list_pages, select_page, navigate_page

• take_snapshot を実行してから click_by_uid / fill_by_uid

• list_network_requests (常時キャプチャ), get_network_request

• screenshot_page, list_console_messages

CLI オプション

フラグまたは環境変数（右側に記載）を渡すことができます:

• --firefox-path — Firefox バイナリへの絶対パス

• --headless — UI なしで実行 (FIREFOX_HEADLESS=true)

• --viewport 1280x720 — 初期ウィンドウサイズ

• --profile-path — 特定の Firefox プロファイルを使用

• --firefox-arg — 追加の Firefox 引数（繰り返し可能）

• --start-url — 開始時にこの URL を開く (START_URL)

• --accept-insecure-certs — TLS エラーを無視 (ACCEPT_INSECURE_CERTS=true)

• --connect-existing — 新しく起動する代わりに、既に実行中の Firefox に接続 (CONNECT_EXISTING=true)

• --marionette-port — 既存接続モード用の Marionette ポート、デフォルト 2828 (MARIONETTE_PORT)

• --pref name=value — moz:firefoxOptions を介して起動時に Firefox 設定を設定（繰り返し可能）

• --enable-script — ページコンテキストで任意の JavaScript を実行する evaluate_script ツールを有効化 (ENABLE_SCRIPT=true)

• --enable-privileged-context — 特権コンテキストツールを有効化: 特権コンテキストのリスト/選択、特権スクリプトの評価、Firefox 設定の取得/設定、拡張機能のリスト。MOZ_REMOTE_ALLOW_SYSTEM_ACCESS=1 が必要 (ENABLE_PRIVILEGED_CONTEXT=true)

--pref に関する注意: Firefox が自動化で実行される際、テスト用にブラウザの動作を変更する RecommendedPreferences が適用されます。--pref オプションを使用すると、必要に応じてこれらのデフォルトを上書きできます。

既存の Firefox への接続

--connect-existing を使用して、Cookie、ログイン情報、開いているタブを維持したまま、実際のブラウジングセッションを自動化します:

# Start Firefox with Marionette enabled
firefox --marionette

# Run the MCP server
npx firefox-devtools-mcp --connect-existing --marionette-port 2828

または、起動のたびに Marionette を有効にするには、about:config (または user.js) で marionette.enabled を true に設定してください。

BiDi 依存機能（コンソールイベント、ネットワークイベント）は既存接続モードでは利用できません。その他の機能はすべて通常通り動作します。

警告: 通常のブラウジング中に Marionette を有効にしたままにしないでください。navigator.webdriver = true が設定され、他のブラウザフィンガープリント信号が変更されるため、Cloudflare や Akamai などで保護されたサイトでボット検出がトリガーされる可能性があります。MCP 自動化が必要なときのみ Marionette を有効にし、その後 Firefox を通常通り再起動してください。

ツール概要

• ページ: list/new/navigate/select/close

• スナップショット/UID: take/resolve/clear

• 入力: click/hover/fill/drag/upload/form fill

• ネットワーク: list/get (ID 優先、フィルタ、常時キャプチャ)

• コンソール: list/clear

• スクリーンショット: page/by uid (CLI 環境用にオプションで saveTo を指定可能)

• スクリプト: evaluate_script

• 特権コンテキスト: 特権（"chrome"）コンテキストのリスト/選択、evaluate_privileged_script (MOZ_REMOTE_ALLOW_SYSTEM_ACCESS=1 が必要)

• WebExtension: install_extension, uninstall_extension, list_extensions (リストには MOZ_REMOTE_ALLOW_SYSTEM_ACCESS=1 が必要)

• Firefox 管理: get_firefox_info, get_firefox_output, restart_firefox, set_firefox_prefs, get_firefox_prefs

• ユーティリティ: ダイアログの accept/dismiss、履歴の戻る/進む、ビューポートの設定

Claude Code 用のスクリーンショット最適化

Claude Code CLI でスクリーンショットを使用する場合、base64 画像データがコンテキストを大幅に消費する可能性があります。代わりに saveTo パラメータを使用してスクリーンショットをディスクに保存してください:

screenshot_page({ saveTo: "/tmp/page.png" })
screenshot_by_uid({ uid: "abc123", saveTo: "/tmp/element.png" })

保存されたファイルは、コンテキストサイズに影響を与えることなく、Claude Code の Read ツールで表示できます。

ローカル開発

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

テスト

npm run test:run          # all tests once (unit + integration)
npm test                  # watch mode

特定のテストスイートの実行、E2E シナリオの網羅範囲、既知の問題については docs/testing.md を参照してください。

トラブルシューティング

• Firefox が見つからない: --firefox-path "/Applications/Firefox.app/Contents/MacOS/firefox" (macOS) または OS 上の正しいパスを渡してください。

• 初回実行が遅い: Selenium が BiDi セッションをセットアップするためです。2回目以降は高速になります。

• ナビゲーション後に UID が古くなる: UID ツールを使用する前に、新しいスナップショット (take_snapshot) を取得してください。

• Windows 10: MCP サーバー 'firefox-devtools' の検出中にエラー - MCP error -32000: Connection closed

  • 解決策 1 cmd /c でラップする (詳細):

    "mcpServers": {
      "firefox-devtools": {
        "command": "cmd",
        "args": ["/c", "npx", "-y", "firefox-devtools-mcp@latest"]
      }
    }

  • 解決策 2 npx への絶対パスを使用する（セットアップに合わせて拡張子 .cmd, .bat, .exe, .ps1 を調整してください）:

    "mcpServers": {
      "firefox-devtools": {
        "command": "C:\\nvm4w\\nodejs\\npx.ps1",
        "args": ["-y", "firefox-devtools-mcp@latest"]
      }
    }

バージョニング

• 1.0 未満の API: バージョンは 0.x から始まります。最新リリースには npx で @latest を使用してください。

CI とリリース

• CI、リリース、npm 公開用の GitHub Actions が含まれています。詳細および必要なシークレットについては docs/ci-and-release.md を参照してください。

問題と貢献

問題は Bugzilla の product: Developer Infrastructure, component: AI for Development で追跡されています。

• 新しい問題を報告する

• メタバグ (すべての firefox-devtools-mcp の問題を追跡)

質問や議論については、#firefox-devtools-mcp Matrix ルーム に参加してください。

作者

Mozilla によって保守されています。