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-серверы несут inherent риски. Несколько ключевых практик:

• Используйте выделенный профиль Firefox. Никогда не запускайте сервер с вашим обычным профилем — агент имеет доступ ко всему, к чему может получить доступ браузер, включая куки и сохранённые сессии.
• Будьте осторожны с посещаемыми сайтами. Страницы могут возвращать контент, предназначенный для манипуляции агентом (инъекция подсказок). Придерживайтесь сайтов, которые вы контролируете или которым доверяете.
• Избегайте включения дополнительных флагов без необходимости. --enable-script и --enable-privileged-context значительно расширяют возможности агента.

См. SECURITY.md для полного описания рисков и инструкций по сообщению об уязвимостях.

Требования

• Node.js ≥ 20.19.0
• Firefox 100+ установлен (автоопределение или передайте --firefox-path)

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

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

Вариант A — Claude Code CLI

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

Вариант B — Редактирование JSON-настроек Claude Code

Добавьте в файл конфигурации 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", "@mozilla/firefox-devtools-mcp@latest", "--headless", "--viewport", "1280x720"],
      "env": {
        "START_URL": "about:blank"
      }
    }
  }
}

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

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
• 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 (можно повторять)
• --enable-script — включить инструмент evaluate_script (выполняет произвольный JavaScript в контексте страницы) и инструменты отладки (список скриптов, просмотр исходного кода, установка точек логирования). Инструменты отладки требуют Firefox 153+. (ENABLE_SCRIPT=true)
• --enable-privileged-context — включить инструменты привилегированного контекста: список/выбор привилегированных контекстов, выполнение привилегированных скриптов, получение/установка настроек Firefox и список расширений. Требует MOZ_REMOTE_ALLOW_SYSTEM_ACCESS=1 (ENABLE_PRIVILEGED_CONTEXT=true)
• --android-device — включить режим Firefox для Android; значение — серийный номер устройства ADB (например, emulator-5554). Выполните adb devices, чтобы увидеть список подключённых устройств. Опустите значение или используйте auto, чтобы автоматически выбрать единственное подключённое устройство.
• --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)
• --log-file — записывать логи MCP-сервера в файл вместо stderr. Полезно для отладки сессий с MCP-клиентами, которые скрывают вывод сервера. Установите DEBUG=*, чтобы также включить подробные отладочные логи. Пример: --log-file /tmp/firefox-mcp.log

Полезные настройки (--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, который управляется автоматически.

# List connected devices
adb devices

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

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

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

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

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

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

# Start Firefox with Marionette enabled
firefox --marionette

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

Или установите marionette.enabled в true в about:config (или user.js), чтобы включить Marionette при каждом запуске.

Функции, зависящие от BiDi (события консоли, сетевые события), недоступны в режиме подключения к существующему; все остальные функции работают нормально.

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

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

• Страницы: список/новая/навигация/выбор/закрытие
• Снимок/UID: создание/разрешение/очистка
• Ввод: клик/наведение/заполнение/перетаскивание/загрузка/заполнение формы
• Сеть: список/получение (сначала ID, фильтры, постоянный захват)
• Консоль: список/очистка
• Скриншот: страницы/по UID (с опциональным saveTo для CLI-окружений)
• Скрипт: 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
• Профилировщик: profiler_is_active, profiler_start (пресет или явная конфигурация), profiler_stop (сохраняет профиль в директорию загрузок)
• Утилиты: принять/отклонить диалог, история назад/вперёд, установить область просмотра

Оптимизация скриншотов для 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

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

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

• Firefox не найден: передайте --firefox-path "/Applications/Firefox.app/Contents/MacOS/firefox" (macOS) или правильный путь в вашей ОС.
• Первый запуск медленный: Selenium устанавливает сессию BiDi; последующие запуски быстрее.
• Устаревшие 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"]
      }
    }
    

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

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

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

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

Автор

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

Лицензия

Лицензировано на выбор под MIT или Apache 2.0.