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 を渡してください）

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 を通常通り再起動してください。

ツール概要

• ページ: リスト/新規/ナビゲート/選択/閉じる

• スナップショット/UID: 取得/解決/クリア

• 入力: クリック/ホバー/入力/ドラッグ/アップロード/フォーム入力

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

• コンソール: リスト/クリア

• スクリーンショット: ページ/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

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

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' の検出中にエラー -32000: Connection closed

  • 解決策 1 cmd を使用して呼び出す (詳細: https://github.com/modelcontextprotocol/servers/issues/1082#issuecomment-2791786310)

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

    重要な変更: Windows では、npx を介して Node.js パッケージを実行する場合、VSCode の拡張機能ホストのような別のプロセス内から正しく実行するために cmd /c プレフィックスが必要になることがよくあります。そのため、"command": "npx" を "command": "cmd" に置き換え、実際の npx コマンドを "args" 配列に移動し、その前に "/c" を付けました。この修正により、Windows はコマンドを正しく解釈し、サーバーを起動できるようになります。

  • 解決策 2 シェルの層を増やす代わりに、npx への絶対パスを記述することもできます:

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

    注意: 上記のパスは例です。お使いの環境での npx の実際の場所に合わせて調整してください。セットアップによっては、ファイル拡張子が .ps1 ではなく .cmd、.bat、または .exe になる場合があります。また、JSON 形式で要求される通り、パスの区切り文字として二重バックスラッシュ (\\) を使用していることを確認してください。

バージョニング

• 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 によって保守されています。