mozilla/firefox-devtools-mcp

WebDriver BiDi (Selenium WebDriver를 통해)를 사용하여 Firefox를 자동화하기 위한 Model Context Protocol (MCP) 서버입니다. 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 프로필을 사용하세요. 에이전트가 쿠키 및 저장된 세션을 포함하여 브라우저가 접근할 수 있는 모든 것에 접근할 수 있으므로, 일반 프로필을 대상으로 서버를 절대 실행하지 마세요.
방문하는 사이트에 주의하세요. 페이지는 에이전트를 조작하도록 설계된 콘텐츠(프롬프트 인젝션 (prompt injection))를 반환할 수 있습니다. 직접 제어하거나 신뢰할 수 있는 사이트만 이용하세요.
필요하지 않다면 추가 플래그 활성화를 피하세요. --enable-script 및 --enable-privileged-context는 에이전트가 할 수 있는 작업을 크게 확장합니다.

위험 요소에 대한 전체 분석 및 취약점 보고 방법은 SECURITY.md를 참조하세요.

• Node.js ≥ 20.19.0
• Firefox 100+ 설치됨 (자동 감지 또는 --firefox-path 전달)

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

옵션 A — Claude Code CLI

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

옵션을 인자(args) 또는 환경 변수(env vars)로 전달할 수 있습니다. 예시:

# 인자를 통한 Headless + 뷰포트(viewport) 설정
claude mcp add firefox-devtools npx @mozilla/firefox-devtools-mcp@latest -- --headless --viewport 1280x720
# 또는 환경 변수를 통한 설정
...

옵션 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": {
...

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

npm run setup
# Claude Code를 선택하세요. 스크립트가 JSON을 올바른 경로에 저장합니다.

npx @modelcontextprotocol/inspector npx @mozilla/firefox-devtools-mcp@latest --start-url https://example.com --headless

그 다음 다음과 같은 도구(tools)를 호출할 수 있습니다:

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

플래그(flags) 또는 환경 변수(오른쪽의 이름)를 전달할 수 있습니다:

--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에 연결 (CONNECT_EXISTING=true)
--marionette-port

— connect-existing 모드를 위한 Marionette 포트, 기본값은 2828 (MARIONETTE_PORT)
--pref name=value

— moz:firefoxOptions를 통해 시작 시 Firefox 설정(preference) 지정 (반복 가능)
--enable-script

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

— 권한 있는 컨텍스트(privileged context) 도구 활성화: 권한 있는 컨텍스트 목록/선택, 권한 있는 스크립트 평가, Firefox 설정 가져오기/설정, 확장 프로그램 목록 보기. MOZ_REMOTE_ALLOW_SYSTEM_ACCESS=1이 필요합니다 (ENABLE_PRIVILEGED_CONTEXT=true)
--android-device

— Android용 Firefox 모드 활성화; 값은 ADB 장치 시리얼 번호입니다 (예: emulator-5554). 연결된 장치 목록을 보려면 adb devices를 실행하세요. 값을 생략하거나 auto를 사용하면 연결된 단일 장치를 자동으로 선택합니다.
--android-package

— Android 앱 패키지 이름, 기본값은 org.mozilla.firefox입니다. 기타 패키지: org.mozilla.firefox_beta

Firefox Beta의 경우, org.mozilla.fenix

Firefox Nightly의 경우, org.mozilla.fenix.debug

Firefox Nightly Debug의 경우, org.mozilla.geckoview_example

geckoview의 경우 (ANDROID_PACKAGE)

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

Android 기기에서 실행되는 Firefox를 자동화하려면 --android-device를 사용하세요. 이 기능을 사용하려면 PATH에 adb가 설정되어 있어야 하며, geckodriver는 자동으로 관리됩니다.

# 연결된 장치 목록 표시
adb devices
# 연결된 단일 장치에서 Android용 Firefox 실행
...

호스트와 장치 간의 포트 포워딩(Port forwarding)은 geckodriver에 의해 자동으로 처리됩니다.

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

# Marionette이 활성화된 상태로 Firefox 시작
firefox --marionette
# MCP 서버 실행
...

또는 about:config (user.js 포함)에서 marionette.enabled를 true로 설정하여 실행할 때마다 Marionette을 활성화할 수 있습니다.

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

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

• 페이지(Pages): list/new/navigate/select/close
• 스냅샷/UID(Snapshot/UID): take/resolve/clear
• 입력(Input): click/hover/fill/drag/upload/form fill
• 네트워크(Network): list/get (ID 우선 방식, 필터, 상시 캡처)
• 콘솔(Console): list/clear
• 스크린샷(Screenshot): page/by uid (CLI 환경을 위한 선택적 saveTo 포함)
• 스크립트(Script): evaluate_script
• 권한 컨텍스트(Privileged Context): 권한이 있는 ("chrome") 컨텍스트 목록/선택, evaluate_privileged_script (MOZ_REMOTE_ALLOW_SYSTEM_ACCESS=1 필요)

) - WebExtension: install_extension, uninstall_extension, list_extensions (list를 호출하려면 MOZ_REMOTE_ALLOW_SYSTEM_ACCESS=1 필요)

) - Firefox Management: get_firefox_info, get_firefox_output, restart_firefox, set_firefox_prefs, get_firefox_prefs

• Utilities: accept/dismiss dialog, history back/forward, set viewport

Claude Code CLI에서 스크린샷을 사용할 때, base64 이미지 데이터는 상당한 컨텍스트 (context)를 소비할 수 있습니다.
대신 saveTo 파라미터를 사용하여 스크린샷을 디스크에 저장하세요:

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

이렇게 하면 컨텍스트 크기에 영향을 주지 않고 Claude Code의 Read 도구로 파일을 볼 수 있습니다.

npm install
npm run build
# 로컬 빌드에 대해 Inspector를 사용하여 실행
...

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

• Firefox를 찾을 수 없는 경우: (macOS의 경우) --firefox-path "/Applications/Firefox.app/Contents/MacOS/firefox"를 전달하거나, 사용 중인 OS의 올바른 경로를 전달하세요.

• 첫 실행이 느린 경우: Selenium이 BiDi 세션을 설정하므로, 이후 실행은 더 빨라집니다.

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

• Windows 10: MCP 서버 'firefox-devtools'의 discovery 중 오류 발생: 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 라이선스 하에 배포됩니다.