firefox-devtools-mcp

Firefox DevTools MCP

AI 에이전트가 Firefox를 사용할 수 있게 해주는 Model Context Protocol 서버입니다. 두 가지 주요 사용 사례가 있습니다:

• 에이전트 기반 브라우징: 에이전트가 페이지 읽기, 양식 작성, 웹사이트의 다단계 흐름 진행과 같은 일반적인 작업에 브라우저를 사용합니다.
• 에이전트 지원 웹 개발: 에이전트가 작업 중인 페이지를 로드하고 콘솔, 네트워크 요청, 디버거, 프로파일러와 같은 개발자 도구로 페이지를 검사합니다.

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 프로필을 사용하세요. 일반 프로필로 서버를 실행하지 마세요 — 에이전트는 브라우저가 도달할 수 있는 모든 것(쿠키 및 저장된 세션 포함)에 접근할 수 있습니다.
• 방문하는 사이트에 주의하세요. 페이지는 에이전트를 조작하도록 설계된 콘텐츠(프롬프트 주입)를 반환할 수 있습니다. 통제하거나 신뢰하는 사이트에만 머무르세요.
• 필요한 도구 모듈만 활성화하세요. 기본 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 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

Codex

codex mcp add firefox-devtools -- npx @mozilla/firefox-devtools-mcp@latest

# Headless + viewport via args
codex mcp add firefox-devtools -- \
  npx @mozilla/firefox-devtools-mcp@latest -- --headless --viewport 1280x720

# Or via environment variables
codex mcp add firefox-devtools \
  --env START_URL=https://example.com \
  --env FIREFOX_HEADLESS=true \
  -- npx @mozilla/firefox-devtools-mcp@latest

옵션 B — 구성 파일 편집

Claude Code

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

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 — 헬퍼 스크립트(로컬 개발 빌드)

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
• 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는 해당 경로의 firefox_devtools_mcp_profile 하위 폴더에서 실행되며 .firefox-devtools-mcp 파일로 표시됩니다. --profile-path을 표시된 프로필로 지정하면 직접 재사용합니다
• --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 — 기존 연결 모드용 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-wipe-app-data — Android 모드가 대상 앱의 모든 데이터를 삭제함을 확인. --android-device와 함께 필요. (ANDROID_WIPE_APP_DATA=true)
• --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)
• --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이 우선하며 프리셋은 무시됩니다.

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

• slim — 페이지를 탐색하고 상호 작용하는 최소 기능
• basic(기본값) — 일반 브라우징 도구 추가
• developer — 웹 개발자용 도구 추가
• mozilla — Firefox 개발자용 도구 추가
• all — 모든 모듈

모듈 목록과 각 프리셋의 모듈은 docs/tools.md를 참조하세요.

기본값인 basic에는 script이 포함되므로 evaluate_script 도구가 포함됩니다. 공격 표면에 대한 의미는 SECURITY.md를 참조하고, 이를 제외하려면 --tool-preset slim 또는 명시적 --tools 목록을 사용하세요.

# Use the developer preset (adds network, console, debugging and profiler tools)
npx @mozilla/firefox-devtools-mcp --tool-preset developer

# Enable only the modules you need
npx @mozilla/firefox-devtools-mcp --tools pages network console

prefs 및 privileged 모듈은 MOZ_REMOTE_ALLOW_SYSTEM_ACCESS=1이 필요하며 Mozilla 내부 빌드에서만 사용할 수 있습니다. launch 모듈도 Mozilla 내부 빌드가 필요합니다: 호출자가 선택한 바이너리, 프로필, 환경 및 기본 설정 집합으로 Firefox를 다시 시작하며, 이는 운영자가 소유해야 하는 구성 변경입니다. 대신 --pref, --firefox-path 및 기타 명령줄 옵션을 사용하세요. bidi 모듈도 Mozilla 내부 빌드가 필요합니다: 모든 WebDriver BiDi 명령을 보내므로 다른 모듈이 노출하는 것에 접근할 수 있습니다. 공개 패키지는 요청된 경우에도 이러한 모듈을 건너뛰고 제외된 모듈 이름을 알리는 경고를 기록합니다.

유용한 기본 설정(--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가 필요합니다.

경고: Android 모드는 세션 전에 대상 앱의 모든 데이터를 삭제합니다. 탭, 기록, 북마크, 비밀번호, 쿠키 및 설정이 모두 손실됩니다. geckodriver는 세션 생성 시 adb shell pm clear <package>을 실행하며 건너뛸 방법이 없고, 이후 삭제되는 자체 임시 프로필에서 세션을 실행합니다. 이 때문에 --android-device에는 --android-wipe-app-data이 필요하며, 사용 중인 브라우저를 자동화하는 대신 자동화 전용 빌드를 설치해야 합니다. Bug 2064088은 기존 앱 데이터를 유지하는 옵션을 geckodriver에 추가하는 것을 추적합니다.

# List connected devices
adb devices

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

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

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

호스트와 장치 간 포트 전달은 geckodriver가 자동으로 처리합니다.

기존 Firefox에 연결

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

# Start Firefox with Marionette and the Remote Agent (BiDi)
firefox --marionette --remote-debugging-port

# Run the MCP server
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 등으로 보호되는 사이트에서 봇 감지를 트리거할 수 있는 다른 브라우저 지문 신호를 변경합니다. MCP 자동화가 필요할 때만 Marionette를 활성화한 후 Firefox를 정상적으로 다시 시작하세요.

도구 개요

모듈별 전체 도구 목록(설명 및 매개변수 포함, 소스에서 생성)은 docs/tools.md를 참조하세요.

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

대용량 도구 출력은 Claude Code와 같은 CLI 클라이언트에서 상당한 컨텍스트를 소비할 수 있습니다. 여러 도구는 선택적 saveTo 매개변수를 허용하여 결과를 인라인으로 반환하는 대신 파일에 기록합니다. 목록은 docs/tools.md를 참조하세요. saveTo은 세 가지 형태 중 하나를 취합니다:

• 파일 경로(현재 작업 디렉토리 기준 상대 경로 또는 ~/.firefox-devtools-mcp/output 내 절대 경로, 상위 디렉토리는 생성됨). Firefox 프로필에 도달하는 경로 또는 이 서버가 다시 읽는 파일은 거부됩니다
• 기존 디렉토리(내부에 타임스탬프 파일이 생성됨)
• true(~/.firefox-devtools-mcp/output/ 아래에 타임스탬프 파일이 생성됨)

응답은 경로와 바이트 크기를 반환합니다. 저장된 파일은 항상 전체, 잘리지 않은 데이터를 보유합니다: 인라인 크기 보호(콘솔 메시지 상한, 네트워크 헤더 잘림, 스냅샷 줄 상한)는 적용되지 않습니다.

텍스트 생성 도구는 또한 preview을 허용하며, 저장된 출력의 문자 수를 짧은 발췌로 인라인 에코백합니다. docs/tools.md의 목록은 어떤 도구가 이를 지원하는지 보여줍니다.

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

# 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는 해당 요소가 제거되거나 페이지가 이동할 때까지 유효합니다. 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 중 하나로 라이선스가 부여됩니다.