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. Никогда не запускайте сервер с вашим обычным профилем — агент имеет доступ ко всему, что доступно браузеру, включая файлы cookie и сохранённые сессии.
Будьте осторожны с посещаемыми сайтами. Страницы могут возвращать контент, предназначенный для манипуляции агентом (инъекция подсказок). Придерживайтесь сайтов, которыми вы управляете или которым доверяете.
Включайте только необходимые модули инструментов. Пресет по умолчанию 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 через аргументы
claude mcp add firefox-devtools npx @mozilla/firefox-devtools-mcp@latest -- --headless --viewport 1280x720

# Или через переменные окружения
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 через аргументы
codex mcp add firefox-devtools -- \
  npx @mozilla/firefox-devtools-mcp@latest -- --headless --viewport 1280x720

# Или через переменные окружения
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
# Выберите Claude Code; скрипт сохранит JSON по правильному пути

Попробуйте с 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 для режима connect-existing, по умолчанию 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, чтобы исключить его.

# Использование пресета developer (добавляет инструменты network, console, debugging и profiler)
npx @mozilla/firefox-devtools-mcp --tool-preset developer

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

# Список подключённых устройств
adb devices

# Запуск Firefox для Android на единственном подключённом устройстве
npx @mozilla/firefox-devtools-mcp --android-device auto --android-wipe-app-data

# Нацеливание на конкретное устройство
npx @mozilla/firefox-devtools-mcp --android-device <serial> --android-wipe-app-data

# Использование Firefox Nightly вместо этого
npx @mozilla/firefox-devtools-mcp --android-device <serial> --android-package org.mozilla.fenix --android-wipe-app-data

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

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

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

# Запуск Firefox с Marionette и Remote Agent (BiDi)
firefox --marionette --remote-debugging-port

# Запуск MCP-сервера
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.

Pages: list/new/navigate/select/close/get_page_text (get_page_text поддерживает необязательный saveTo)
Snapshot/UID: take/resolve/clear (take поддерживает необязательный saveTo)
Input: click/hover/fill/drag/upload/form fill/press_key/type_text
Network: list/get (сначала ID, фильтры, постоянный захват; оба поддерживают необязательный saveTo)
Downloads: list_downloads/clear_downloads (постоянный захват), set_download_behavior (allow/deny/default)
Console: list/clear (list поддерживает необязательный saveTo)
Screenshot: page/by uid (с необязательным saveTo для сред CLI)
Script: evaluate_script (необязательный sandbox для изолированной области; необязательный saveTo для объёмных результатов)
Privileged Context: 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 Management: get_firefox_info, get_firefox_output, restart_firefox
Firefox Preferences: get_firefox_prefs, set_firefox_prefs (требует MOZ_REMOTE_ALLOW_SYSTEM_ACCESS=1)
Profiler: profiler_is_active, profiler_start (пресет или явная конфигурация), profiler_stop (сохраняет профиль в каталог загрузок)
Screencast: screencast_start (записывает область просмотра страницы в видеофайл в каталоге загрузок), screencast_stop (требует Firefox 154+)
Utilities: 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

# Запуск с Inspector против локальной сборки
npx @modelcontextprotocol/inspector node dist/index.js --headless --viewport 1280x720

# Или запуск в dev-режиме с горячей перезагрузкой
npm run inspector:dev

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

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

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 на ваш выбор.

firefox-devtools-mcp v0.10.2

Категории

firefox-devtools-mcp v0.10.2

Firefox DevTools MCP

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

Требования

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

Вариант A — CLI

Claude Code

Codex

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

Claude Code

Codex

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

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

Параметры CLI

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

Полезные настройки (--pref)

Firefox для Android

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

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

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

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

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

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

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

Автор

Лицензия

Категории

Полезные настройки (`--pref`)