firefox-devtools-mcp

Firefox DevTools MCP

WebDriver BiDi(Selenium WebDriver 경유)를 통해 Firefox를 자동화하기 위한 모델 컨텍스트 프로토콜 서버입니다. 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 프로필을 사용하세요. 일반 프로필로 서버를 실행하지 마세요. 에이전트는 쿠키 및 저장된 세션을 포함하여 브라우저가 접근할 수 있는 모든 것에 접근할 수 있습니다.
• 방문하는 사이트에 주의하세요. 페이지는 에이전트를 조작하도록 설계된 콘텐츠(프롬프트 인젝션)를 반환할 수 있습니다. 제어하거나 신뢰하는 사이트만 사용하세요.
• 필요하지 않은 경우 추가 플래그를 활성화하지 마세요. --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 — 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
# 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 — 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 환경 설정 지정 (반복 가능)
• --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 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 — 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. Firefox에서 상세 WebDriver 프로토콜 로그를 활성화합니다. MCP 서버는 자동으로 일치하는 로그 레벨을 geckodriver에 전달하여 양측이 동일한 상세 수준으로 로깅하도록 합니다.
• app.update.disabledForTesting=false. Firefox가 자동으로 업데이트를 다운로드하고 적용하도록 허용합니다. 업데이트로 인해 세션이 중단될 수 있습니다. remote.prefs.recommended=false 설정도 필요합니다.

Firefox for Android

--android-device을 사용하여 Android 기기에서 실행되는 Firefox를 자동화하세요. PATH에 adb 및 자동으로 관리되는 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

또는 about:config (또는 user.js)에서 marionette.enabled을 true로 설정하여 모든 실행 시 Marionette를 활성화합니다.

BiDi 종속 기능(콘솔 이벤트, 네트워크 이벤트)은 connect-existing 모드에서 사용할 수 없습니다. 다른 모든 기능은 정상적으로 작동합니다.

경고: 일반 브라우징 중에는 Marionette를 활성화된 상태로 두지 마세요. navigator.webdriver = true을 설정하고 다른 브라우저 핑거프린트 신호를 변경하여 Cloudflare, Akamai 등으로 보호되는 사이트에서 봇 탐지를 유발할 수 있습니다. MCP 자동화가 필요할 때만 Marionette를 활성화한 다음, 이후에는 Firefox를 정상적으로 다시 시작하세요.

도구 개요

• 페이지: 나열/새로 만들기/이동/선택/닫기
• 스냅샷/UID: 가져오기/해석/지우기
• 입력: 클릭/호버/채우기/드래그/업로드/양식 채우기
• 네트워크: 나열/가져오기 (ID 우선, 필터, 상시 캡처)
• 콘솔: 나열/지우기
• 스크린샷: 페이지/UID별 (CLI 환경용 선택적 saveTo 포함)
• 스크립트: 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

로컬 개발, 테스트 및 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 오류 -32000: 연결이 닫혔습니다

  • 해결책 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에 따라 라이선스가 부여됩니다.