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 @mozilla/firefox-devtools-mcp@latest를 사용하거나 제공된 Dockerfile로 Docker를 사용하세요.

보안

브라우저 MCP 서버는 본질적인 위험을 수반합니다. 핵심 수칙 몇 가지:

전용 Firefox 프로필을 사용하세요. 일반 프로필에 대해 서버를 실행하지 마십시오 — 에이전트는 브라우저가 도달할 수 있는 모든 것(쿠키 및 저장된 세션 포함)에 접근할 수 있습니다.
방문하는 사이트에 주의하세요. 페이지는 에이전트를 조작하도록 설계된 콘텐츠(프롬프트 인젝션)를 반환할 수 있습니다. 직접 제어하거나 신뢰하는 사이트만 방문하세요.
필요한 도구 모듈만 활성화하세요. --tool-preset developer(script, debugging) 및 --tool-preset mozilla(권한 있는 컨텍스트)와 같은 상위 프리셋은 에이전트가 수행할 수 있는 작업을 크게 확장합니다.

위험에 대한 전체 분석과 취약점 신고 방법은 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

옵션을 인자 또는 환경 변수로 전달하세요. 예:

# 인자를 통한 헤드리스 + 뷰포트
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

옵션 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", "@mozilla/firefox-devtools-mcp@latest", "--headless", "--viewport", "1280x720"],
      "env": {
        "START_URL": "about:blank"
      }
    }
  }
}

옵션 C — 헬퍼 스크립트 (로컬 개발 빌드)

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 — 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를 실행하는 대신 이미 실행 중인 Firefox에 연결 (CONNECT_EXISTING=true)
--marionette-port — connect-existing 모드용 Marionette 포트, 기본값 2828 (MARIONETTE_PORT)
--pref name=value — 시작 시 moz:firefoxOptions를 통해 Firefox 기본 설정 지정 (반복 가능)
--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 for Android 모드 활성화; 값은 ADB 기기 시리얼입니다 (예: emulator-5554). 연결된 기기를 나열하려면 adb devices를 실행하세요. 값을 생략하거나 auto를 사용하여 연결된 단일 기기를 자동으로 선택하세요.
--android-package — Android 앱 패키지 이름, 기본값 org.mozilla.firefox. 기타 패키지: Firefox Beta는 org.mozilla.firefox_beta, Firefox Nightly는 org.mozilla.fenix, Firefox Nightly Debug는 org.mozilla.fenix.debug, geckoview는 org.mozilla.geckoview_example (ANDROID_PACKAGE)
--log-file — stderr 대신 파일에 MCP 서버 로그를 기록합니다. 서버 출력을 숨기는 MCP 클라이언트와의 디버깅 세션에 유용합니다. 상세 디버그 로그도 포함하려면 DEBUG=*를 설정하세요. 예: --log-file /tmp/firefox-mcp.log

도구 모듈 및 프리셋

도구는 모듈로 그룹화됩니다. 명명된 프리셋(--tool-preset) 또는 명시적 목록(--tools)으로 노출할 모듈을 선택합니다. 둘 다 제공되면 --tools가 우선하며 프리셋은 무시됩니다.

모듈: pages, snapshot, input, network, console, screenshot, utilities, management, webextension, profiler, screencast, script, debugging, prefs, privileged.

프리셋 (각각 이전 프리셋의 상위 집합):

slim — pages, snapshot, input, network, console
basic (기본값) — slim + screenshot, utilities, management, webextension, profiler, screencast
developer — basic + script, debugging
mozilla — developer + prefs, privileged
all — 모든 모듈

# developer 프리셋 사용 (script 및 debugging 도구 추가)
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를 적용합니다. 이를 건너뛰고 일반 Firefox 인스턴스에 더 가까운 구성을 가지려면 remote.prefs.recommended를 false로 설정하세요.
remote.log.level=Trace. Firefox에서 상세 WebDriver 프로토콜 로그를 활성화합니다. MCP 서버는 일치하는 로그 수준을 geckodriver에 자동으로 전달하므로 양쪽 모두 동일한 상세 수준으로 로그를 기록합니다.
app.update.disabledForTesting=false. Firefox가 업데이트를 자동으로 다운로드하고 적용하도록 허용합니다. 업데이트가 세션을 방해할 수 있습니다. 또한 remote.prefs.recommended=false를 설정해야 합니다.

Firefox for Android

--android-device를 사용하여 Android 기기에서 실행 중인 Firefox를 자동화하세요. PATH에 adb와 자동으로 관리되는 geckodriver가 필요합니다.

# 연결된 기기 나열
adb devices

# 연결된 단일 기기에서 Firefox for Android 실행
npx @mozilla/firefox-devtools-mcp --android-device auto

# 특정 기기 지정
npx @mozilla/firefox-devtools-mcp --android-device <serial>

# 대신 Firefox Nightly 사용
npx @mozilla/firefox-devtools-mcp --android-device <serial> --android-package org.mozilla.fenix

호스트와 기기 간 포트 포워딩은 geckodriver가 자동으로 처리합니다.

기존 Firefox에 연결

--connect-existing을 사용하여 쿠키, 로그인 및 열린 탭이 그대로 유지된 실제 브라우징 세션을 자동화하세요:

# Marionette 및 Remote Agent (BiDi)로 Firefox 시작
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를 활성화된 상태로 두지 마십시오. Marionette는 navigator.webdriver = true를 설정하고 다른 브라우저 핑거프린트 신호를 변경하여 Cloudflare, Akamai 등으로 보호되는 사이트에서 봇 탐지를 유발할 수 있습니다. MCP 자동화가 필요할 때만 Marionette를 활성화하고 이후 Firefox를 정상적으로 다시 시작하세요.

도구 개요

페이지: list/new/navigate/select/close
스냅샷/UID: take/resolve/clear (take는 선택적 saveTo 지원)
입력: click/hover/fill/drag/upload/form fill <<<<<<< HEAD
네트워크: list/get (ID 우선, 필터, 상시 캡처; 둘 다 선택적 saveTo 지원)
콘솔: list/clear (list는 선택적 saveTo 지원) =======
네트워크: list/get (ID 우선, 필터, 상시 캡처)
다운로드: list_downloads/clear_downloads (상시 캡처), set_download_behavior (allow/deny/default)
콘솔: list/clear

6873767 (Bug 2055949 - [firefox-devtools-mcp] expose download events to firefox devtools mcp)

스크린샷: page/by uid (CLI 환경용 선택적 saveTo 포함)
스크립트: evaluate_script (대용량 결과용 선택적 saveTo 포함)
권한 있는 컨텍스트: 권한 있는("chrome") 컨텍스트 list/select, 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, set_firefox_prefs, get_firefox_prefs
프로파일러: profiler_is_active, profiler_start (프리셋 또는 명시적 구성), profiler_stop (프로필을 다운로드 디렉터리에 저장)
스크린캐스트: screencast_start (페이지 뷰포트를 다운로드 디렉터리의 비디오 파일로 녹화), screencast_stop (Firefox 154+ 필요)
유틸리티: 대화상자 accept/dismiss, 기록 back/forward, 뷰포트 설정

대용량 출력을 디스크에 저장

대용량 도구 출력은 Claude Code와 같은 CLI 클라이언트에서 상당한 컨텍스트를 소비할 수 있습니다. screenshot_page, screenshot_by_uid, take_snapshot, list_console_messages, list_network_requests, get_network_request, 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로 서버를 시작하세요.

그런 다음 저장된 파일은 컨텍스트 크기에 영향을 주지 않고 Claude Code의 Read 도구로 볼 수 있습니다.

로컬 개발

npm install
npm run build

# 로컬 빌드로 Inspector 실행
npx @modelcontextprotocol/inspector node dist/index.js --headless --viewport 1280x720

# 또는 핫 리로드로 개발 모드 실행
npm run inspector:dev

로컬 개발, 테스트 및 CI에 대한 자세한 내용은 CONTRIBUTING.md를 참조하세요.

문제 해결

Firefox를 찾을 수 없음: --firefox-path "/Applications/Firefox.app/Contents/MacOS/firefox"(macOS) 또는 OS에 맞는 올바른 경로를 전달하세요.
첫 실행이 느림: Selenium이 BiDi 세션을 설정합니다. 이후 실행은 더 빠릅니다.
탐색 후 오래된 UID: UID 도구를 사용하기 전에 새 스냅샷(take_snapshot)을 찍으세요.

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"]
  }
}

버전 관리

1.0 이전 API: 버전은 0.x에서 시작합니다. 최신 릴리스에는 npx와 함께 @latest를 사용하세요.

기여

이슈를 제출하고, 테스트를 실행하고, 프로젝트를 로컬에서 작업하는 방법은 CONTRIBUTING.md를 참조하세요.

저자

Mozilla가 유지 관리합니다.

라이선스

선택에 따라 MIT 또는 Apache 2.0 중 하나에 따라 라이선스가 부여됩니다.

firefox-devtools-mcp v0.10.0

카테고리