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

요구 사항

• Node.js ≥ 20.19.0

• Firefox 100+ 설치됨 (자동 감지되거나 --firefox-path로 전달)

Claude Code와 함께 설치 및 사용 (npx)

권장 사항: npm에서 게시된 최신 버전을 항상 실행할 수 있도록 npx를 사용하세요.

옵션 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 — 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", "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 — 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 — 기존 연결 모드를 위한 Marionette 포트, 기본값 2828 (MARIONETTE_PORT)

• --pref name=value — moz:firefoxOptions를 통해 시작 시 Firefox 기본 설정 지정 (반복 가능)

• --enable-script — 페이지 컨텍스트에서 임의의 JavaScript를 실행하는 evaluate_script 도구 활성화 (ENABLE_SCRIPT=true)

• --enable-privileged-context — 권한 있는 컨텍스트 도구 활성화: 권한 있는 컨텍스트 나열/선택, 권한 있는 스크립트 평가, Firefox 기본 설정 가져오기/설정, 확장 프로그램 나열. MOZ_REMOTE_ALLOW_SYSTEM_ACCESS=1 필요 (ENABLE_PRIVILEGED_CONTEXT=true)

--pref 참고: Firefox가 자동화 모드로 실행될 때, 테스트를 위해 브라우저 동작을 수정하는 RecommendedPreferences가 적용됩니다. --pref 옵션을 사용하면 필요할 때 이러한 기본값을 재정의할 수 있습니다.

기존 Firefox에 연결

--connect-existing을 사용하여 쿠키, 로그인 정보, 열려 있는 탭을 그대로 유지한 채 실제 브라우징 세션을 자동화하세요:

# Start Firefox with Marionette enabled
firefox --marionette

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

또는 모든 실행 시 Marionette를 활성화하려면 about:config(또는 user.js)에서 marionette.enabled를 true로 설정하세요.

BiDi 의존 기능(콘솔 이벤트, 네트워크 이벤트)은 기존 연결 모드에서는 사용할 수 없으며, 다른 모든 기능은 정상적으로 작동합니다.

경고: 일반 브라우징 중에 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 필요)

• 웹 확장 프로그램: 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" })

저장된 파일은 컨텍스트 크기에 영향을 주지 않고 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

테스트

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

특정 테스트 스위트 실행, e2e 시나리오 커버리지 및 알려진 문제에 대한 자세한 내용은 docs/testing.md를 참조하세요.

문제 해결

• Firefox를 찾을 수 없음: --firefox-path "/Applications/Firefox.app/Contents/MacOS/firefox"(macOS) 또는 운영체제의 올바른 경로를 전달하세요.

• 첫 실행이 느림: Selenium이 BiDi 세션을 설정하는 과정이며, 이후 실행은 더 빠릅니다.

• 탐색 후 UID가 유효하지 않음: UID 도구를 사용하기 전에 새로운 스냅샷(take_snapshot)을 찍으세요.

• Windows 10: MCP 서버 'firefox-devtools' 검색 중 오류 발생 - MCP 오류 -32000: 연결이 닫혔습니다.

  • 해결 방법 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에서 npx를 통해 Node.js 패키지를 실행할 때 VSCode의 확장 호스트와 같은 다른 프로세스 내에서 올바르게 실행되려면 cmd /c 접두사가 필요한 경우가 많습니다. 따라서 "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 위치에 맞게 조정해야 합니다. 설정에 따라 파일 확장자가 .ps1이 아닌 .cmd, .bat 또는 .exe일 수 있습니다. 또한 JSON 형식에서 요구하는 대로 경로 구분 기호로 이중 백슬래시(\\)를 사용해야 합니다.

버전 관리

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

CI 및 릴리스

• CI, 릴리스 및 npm 게시를 위한 GitHub Actions가 포함되어 있습니다. 자세한 내용과 필요한 보안 정보는 docs/ci-and-release.md를 참조하세요.

문제 및 기여

문제는 Bugzilla의 product: Developer Infrastructure, component: AI for Development에서 추적됩니다.

• 새 문제 제기

• 메타 버그 (모든 firefox-devtools-mcp 문제 추적)

질문 및 토론은 #firefox-devtools-mcp Matrix 대화방에 참여하세요.

작성자

Mozilla에서 유지 관리합니다.