Firefox DevTools MCP

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

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

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

Требования

• Node.js ≥ 20.19.0

• Установленный Firefox 100+ (определяется автоматически или передайте --firefox-path)

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

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

Вариант 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 — Редактирование 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", "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 — запуск без графического интерфейса (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 в контексте страницы (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.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

• Утилиты: принятие/отклонение диалоговых окон, история назад/вперед, установка области просмотра

Оптимизация скриншотов для Claude Code

При использовании скриншотов в Claude Code CLI данные изображения в формате base64 могут занимать значительный объем контекста. Используйте параметр saveTo для сохранения скриншотов на диск:

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

Файл можно просмотреть с помощью инструмента 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

Тестирование

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

См. docs/testing.md для получения полной информации о запуске конкретных наборов тестов, покрытии сценариев e2e и известных проблемах.

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

• 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 (Дополнительная информация: https://github.com/modelcontextprotocol/servers/issues/1082#issuecomment-2791786310)

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

    Ключевое изменение: В Windows запуск пакета Node.js через npx часто требует префикса cmd /c для правильного выполнения из другого процесса, например, хоста расширений VSCode. Поэтому "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 на вашем компьютере. В зависимости от вашей настройки расширение файла может быть .cmd, .bat или .exe, а не .ps1. Также убедитесь, что вы используете двойную обратную косую черту (\\) в качестве разделителей пути, как того требует формат JSON.

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

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

CI и релизы

• Включены GitHub Actions для CI, релизов и публикации в npm. Подробности и необходимые секреты см. в docs/ci-and-release.md.

Проблемы и участие

Проблемы отслеживаются в Bugzilla в разделе product: Developer Infrastructure, component: AI for Development.

• Создать новую проблему

• Мета-баг (отслеживает все проблемы firefox-devtools-mcp)

Для вопросов и обсуждения присоединяйтесь к Matrix-комнате #firefox-devtools-mcp.

Автор

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