firefox-devtools-mcp

Firefox DevTools MCP

Сервер Model Context Protocol для автоматизации Firefox через WebDriver BiDi (посредством Selenium WebDriver). Работает с Claude Code, Claude Desktop, Cursor, Cline и другими MCP-клиентами.

Репозиторий: https://github.com/mozilla/firefox-devtools-mcp

Примечание: Этот MCP-сервер требует локальной установки браузера Firefox и не может работать в облачных хостингах, таких как glama.ai. Используйте npx @mozilla/firefox-devtools-mcp@latest для локального запуска или Docker с предоставленным Dockerfile.

Безопасность

Браузерные MCP-серверы несут в себе неотъемлемые риски. Несколько ключевых практик:

• Используйте выделенный профиль Firefox. Никогда не запускайте сервер с вашим обычным профилем — агент имеет доступ ко всему, что доступно браузеру, включая куки и сохранённые сессии.
• Будьте осторожны с посещаемыми сайтами. Страницы могут содержать контент, предназначенный для манипуляции агентом (инъекция промптов). Придерживайтесь сайтов, которыми вы управляете или которым доверяете.
• Включайте только нужные модули инструментов. Пресет по умолчанию basic уже включает evaluate_script; --tool-preset slim исключает его. Более высокие пресеты, такие как --tool-preset developer (отладка, сеть, консоль, профилировщик) и --tool-preset mozilla (привилегированный контекст), расширяют возможности агента.

Полный перечень рисков и информацию о том, как сообщать об уязвимостях, см. в SECURITY.md.

Требования

• Node.js ≥ 20.19.0
• Firefox 100+ установлен (автоматически определяется или передаётся через --firefox-path)

Установка и использование с Claude Code или Codex (npx)

Рекомендуется: используйте npx, чтобы запускать последнюю опубликованную версию из npm.

Вариант A — CLI

Claude Code

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

# Headless + viewport via args
claude mcp add firefox-devtools npx @mozilla/firefox-devtools-mcp@latest -- --headless --viewport 1280x720

# Or via environment variables
claude mcp add firefox-devtools npx @mozilla/firefox-devtools-mcp@latest \
  --env START_URL=https://example.com \
  --env FIREFOX_HEADLESS=true

Codex

codex mcp add firefox-devtools -- npx @mozilla/firefox-devtools-mcp@latest

# Headless + viewport via args
codex mcp add firefox-devtools -- \
  npx @mozilla/firefox-devtools-mcp@latest -- --headless --viewport 1280x720

# Or via environment variables
codex mcp add firefox-devtools \
  --env START_URL=https://example.com \
  --env FIREFOX_HEADLESS=true \
  -- npx @mozilla/firefox-devtools-mcp@latest

Вариант B — Редактирование файла конфигурации

Claude Code

Добавьте в mcp_settings.json Claude Code:

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

Codex

Добавьте в ~/.codex/config.toml:

[mcp_servers.firefox-devtools]
command = "npx"
args = ["-y", "@mozilla/firefox-devtools-mcp@latest", "--headless", "--viewport", "1280x720"]

[mcp_servers.firefox-devtools.env]
START_URL = "about:blank"

Вариант C — Вспомогательный скрипт (локальная dev-сборка)

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

Попробуйте с MCP Inspector

npx @modelcontextprotocol/inspector npx @mozilla/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
• list_downloads (постоянный захват), set_download_behavior
• screenshot_page, list_console_messages

Параметры CLI

Вы можете передавать флаги или переменные окружения (имена справа):

• --firefox-path — абсолютный путь к исполняемому файлу Firefox
• --headless — запуск без интерфейса (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 — установить предпочтение Firefox при запуске через moz:firefoxOptions (повторяемый)
• --tool-preset — выбор модулей инструментов: slim, basic (по умолчанию), developer, mozilla или all. См. Модули инструментов и пресеты. (TOOL_PRESET)
• --tools — явный список модулей инструментов, полностью переопределяющий --tool-preset (например, --tools pages network script). См. Модули инструментов и пресеты.
• --enable-script — устарело, используйте --tool-preset developer или --tools ... script debugging. Выбирает пресет инструментов developer. (ENABLE_SCRIPT=true)
• --enable-privileged-context — устарело, используйте --tool-preset mozilla или --tools ... privileged prefs. Выбирает пресет инструментов mozilla. Требует MOZ_REMOTE_ALLOW_SYSTEM_ACCESS=1 (ENABLE_PRIVILEGED_CONTEXT=true)
• --android-device — включить режим Firefox для Android; значение — серийный номер ADB-устройства (например, emulator-5554). Выполните adb devices для вывода списка подключённых устройств. Опустите значение или используйте auto для автоматического выбора единственного подключённого устройства.
• --android-wipe-app-data — подтверждение того, что режим Android стирает все данные целевого приложения. Обязателен вместе с --android-device. (ANDROID_WIPE_APP_DATA=true)
• --android-package — имя пакета приложения Android, по умолчанию org.mozilla.firefox. Другие пакеты: org.mozilla.firefox_beta для Firefox Beta, org.mozilla.fenix для Firefox Nightly, org.mozilla.fenix.debug для Firefox Nightly Debug, org.mozilla.geckoview_example для geckoview (ANDROID_PACKAGE)
• --unrestricted-save-paths — разрешить параметру saveTo запись в любое место на диске вместо корневых каталогов по умолчанию. См. Сохранение объёмных результатов на диск и примечание по безопасности в SECURITY.md. (UNRESTRICTED_SAVE_PATHS=true)
• --log-file — запись журналов MCP-сервера в файл вместо stderr. Полезно для отладки сессий с MCP-клиентами, скрывающими вывод сервера. Установите DEBUG=* для включения подробных отладочных журналов. Пример: --log-file /tmp/firefox-mcp.log

Модули инструментов и пресеты

Инструменты сгруппированы в модули. Вы выбираете, какие модули открыть, либо с помощью именованного пресета (--tool-preset), либо с помощью явного списка (--tools). Если указаны оба, --tools имеет приоритет, а пресет игнорируется.

Модули: pages, snapshot, input, network, console, screenshot, downloads, utilities, management, webextension, profiler, screencast, script, debugging, prefs, privileged.

Пресеты (каждый является надмножеством предыдущего):

• slim — pages, snapshot, input, screenshot
• basic (по умолчанию) — slim плюс downloads, script, utilities, management, webextension, screencast
• developer — basic плюс debugging, network, console, profiler
• mozilla — developer плюс prefs, privileged
• all — каждый модуль

Обратите внимание, что basic, пресет по умолчанию, включает script и, следовательно, инструмент evaluate_script. См. SECURITY.md о том, что это означает для поверхности атаки, и используйте --tool-preset slim или явный список --tools, чтобы исключить его.

# Use the developer preset (adds network, console, debugging and profiler tools)
npx @mozilla/firefox-devtools-mcp --tool-preset developer

# Enable only the modules you need
npx @mozilla/firefox-devtools-mcp --tools pages network console

Модули prefs и privileged требуют MOZ_REMOTE_ALLOW_SYSTEM_ACCESS=1 и доступны только во внутренней сборке Mozilla. Публичный пакет пропускает их, даже если они запрошены, и записывает предупреждение с указанием имён исключённых модулей.

Полезные предпочтения (--pref)

• remote.prefs.recommended=false. Когда Firefox работает в режиме автоматизации, он применяет RecommendedPreferences, изменяющие поведение браузера для тестирования. Установите remote.prefs.recommended в false, чтобы пропустить их и получить конфигурацию, близкую к обычному экземпляру Firefox.
• remote.log.level=Trace. Включите подробные журналы протокола WebDriver в Firefox. MCP-сервер автоматически передаст соответствующий уровень журналирования в geckodriver, чтобы обе стороны записывали журналы с одинаковой детализацией.
• app.update.disabledForTesting=false. Разрешить Firefox автоматически загружать и применять обновления. Обратите внимание, что обновления могут прервать вашу сессию. Также требует установки remote.prefs.recommended=false.

Firefox для Android

Используйте --android-device для автоматизации Firefox, работающего на Android-устройстве. Требует adb в вашем PATH и geckodriver, который управляется автоматически.

Предупреждение: Режим Android стирает все данные целевого приложения перед каждой сессией. Вкладки, история, закладки, пароли, куки и настройки — всё теряется. geckodriver запускает adb shell pm clear <package> при создании сессии и не предлагает способа пропустить это, затем запускает сессию в собственном временном профиле, который удаляется после. Из-за этого --android-device требует --android-wipe-app-data, и вам следует установить сборку, предназначенную для автоматизации, а не автоматизировать браузер, которым вы пользуетесь. Bug 2064088 отслеживает добавление опции в geckodriver для сохранения существующих данных приложения.

# List connected devices
adb devices

# Launch Firefox for Android on the single connected device
npx @mozilla/firefox-devtools-mcp --android-device auto --android-wipe-app-data

# Target a specific device
npx @mozilla/firefox-devtools-mcp --android-device <serial> --android-wipe-app-data

# Use Firefox Nightly instead
npx @mozilla/firefox-devtools-mcp --android-device <serial> --android-package org.mozilla.fenix --android-wipe-app-data

Переадресация портов между хостом и устройством обрабатывается автоматически geckodriver.

Подключение к существующему Firefox

Используйте --connect-existing для автоматизации вашей реальной сессии браузера с сохранением куки, логинов и открытых вкладок:

# Start Firefox with Marionette and the Remote Agent (BiDi)
firefox --marionette --remote-debugging-port

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

Оба флага обязательны, поскольку MCP использует и WebDriver Classic (--marionette), и WebDriver BiDi (--remote-debugging-port). Если Firefox запущен только с --marionette, MCP-сервер не сможет подключиться и попросит перезапустить Firefox с обоими флагами.

Предупреждение: Не оставляйте Marionette включённым во время обычного просмотра. Он устанавливает navigator.webdriver = true и изменяет другие сигналы цифрового отпечатка браузера, что может вызвать обнаружение ботов на сайтах, защищённых Cloudflare, Akamai и т.п. Включайте Marionette только когда нужна MCP-автоматизация, затем перезапускайте Firefox в обычном режиме.

Обзор инструментов

Полный список инструментов по модулям с описаниями и параметрами (сгенерирован из исходного кода) см. в docs/tools.md.

• Страницы: list/new/navigate/select/close/get_page_text (get_page_text поддерживает необязательный saveTo)
• Снимок/UID: take/resolve/clear (take поддерживает необязательный saveTo)
• Ввод: click/hover/fill/drag/upload/form fill
• Сеть: list/get (ID-первый, фильтры, постоянный захват; оба поддерживают необязательный saveTo)
• Загрузки: list_downloads/clear_downloads (постоянный захват), set_download_behavior (allow/deny/default)
• Консоль: list/clear (list поддерживает необязательный saveTo)
• Снимок экрана: page/by uid (с необязательным saveTo для CLI-сред)
• Скрипт: evaluate_script (необязательный sandbox для изолированной области; необязательный saveTo для объёмных результатов)
• Привилегированный контекст: list/select привилегированных ("chrome") контекстов, evaluate_privileged_script (требует MOZ_REMOTE_ALLOW_SYSTEM_ACCESS=1)
• WebExtension: install_extension, uninstall_extension, list_extensions (list требует MOZ_REMOTE_ALLOW_SYSTEM_ACCESS=1)
• Управление Firefox: get_firefox_info, get_firefox_output, restart_firefox
• Предпочтения Firefox: get_firefox_prefs, set_firefox_prefs (требует MOZ_REMOTE_ALLOW_SYSTEM_ACCESS=1)
• Профилировщик: profiler_is_active, profiler_start (пресет или явная конфигурация), profiler_stop (сохраняет профиль в каталог загрузок)
• Скринкаст: screencast_start (записывает область просмотра страницы в видеофайл в каталоге загрузок), screencast_stop (требует Firefox 154+)
• Утилиты: accept/dismiss dialog, history back/forward, set viewport

Сохранение объёмных результатов на диск

Большой вывод инструментов может потреблять значительный контекст в CLI-клиентах, таких как Claude Code. Инструменты screenshot_page, screenshot_by_uid, take_snapshot, list_console_messages, list_network_requests, get_network_request, get_page_text, evaluate_script и evaluate_privileged_script принимают необязательный параметр saveTo, который записывает результат в файл вместо возврата встроенного. saveTo принимает одну из трёх форм:

• путь к файлу (относительно текущего рабочего каталога или абсолютный в пределах ~/.firefox-devtools-mcp; родительские каталоги создаются)
• существующий каталог (внутри него создаётся файл с отметкой времени)
• true (файл с отметкой времени создаётся в ~/.firefox-devtools-mcp/output/)

Ответ возвращает путь и размер в байтах. Сохранённый файл всегда содержит полные, неусечённые данные: встроенные ограничения размера (ограничения сообщений консоли, усечение заголовков сети, ограничения строк снимка) к нему никогда не применяются.

Инструменты, создающие текст (все, кроме снимков экрана), также принимают preview — число символов сохранённого вывода для возврата встроенно в качестве краткого фрагмента. Снимки экрана не имеют предпросмотра.

screenshot_page({ saveTo: "page.png" })
take_snapshot({ saveTo: true })
list_network_requests({ urlContains: "api", saveTo: "network.json" })
evaluate_script({ function: "() => performance.getEntries()", saveTo: true, preview: 2000 })

По умолчанию пути сохранения ограничены: относительные пути разрешаются относительно текущей рабочей директории, а абсолютные пути допускаются только внутри ~/.firefox-devtools-mcp. Пути, выходящие за эти пределы, отклоняются. Запустите сервер с флагом --unrestricted-save-paths, чтобы разрешить запись в произвольные места, включая абсолютные пути за пределами этой директории.

Сохранённые файлы затем можно просматривать, например, с помощью инструмента Read в Claude Code, не влияя на размер контекста.

Локальная разработка

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

См. CONTRIBUTING.md для получения дополнительных сведений о локальной разработке, тестировании и CI.

Устранение неполадок

• Firefox не найден: передайте --firefox-path "/Applications/Firefox.app/Contents/MacOS/firefox" (macOS) или правильный путь для вашей ОС.
• Первый запуск медленный: Selenium настраивает сеанс BiDi; последующие запуски выполняются быстрее.
• Устаревшие UID: UID остаётся действительным, пока его элемент не удалён или страница не перезагружена; сделайте новый снимок (take_snapshot), когда инструмент UID сообщает, что элемент исчез.
• Windows 10: Ошибка при обнаружении MCP-сервера 'firefox-devtools': MCP error -32000: Connection closed

  • Решение 1 Оберните с помощью cmd /c (подробности):

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

  • Решение 2 Используйте абсолютный путь к npx (настройте расширение — .cmd, .bat, .exe или .ps1 — в соответствии с вашей конфигурацией):

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

Версионирование

• API до версии 1.0: версии начинаются с 0.x. Используйте @latest с npx для получения последнего релиза.

Участие в разработке

См. CONTRIBUTING.md для получения информации о том, как сообщать об ошибках, запускать тесты и работать над проектом локально.

Автор

Поддерживается Mozilla.

Лицензия

Лицензировано на условиях MIT или Apache 2.0 на ваш выбор.