# Firefox DevTools MCP

[![npm version](https://badge.fury.io/js/@mozilla/firefox-devtools-mcp.svg)](https://www.npmjs.com/package/@mozilla/firefox-devtools-mcp)
[![CI](https://github.com/mozilla/firefox-devtools-mcp/workflows/CI/badge.svg)](https://github.com/mozilla/firefox-devtools-mcp/actions/workflows/ci.yml)
[![codecov](https://codecov.io/gh/mozilla/firefox-devtools-mcp/branch/main/graph/badge.svg)](https://codecov.io/gh/mozilla/firefox-devtools-mcp)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE-MIT) [![License: Apache 2.0](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](LICENSE-APACHE)

<a href="https://glama.ai/mcp/servers/@mozilla/firefox-devtools-mcp"><img src="https://assets.kitploit.com/production/public/readmes/8655/a78a7d97ae218a4638aa3f14a824feef8d0e205b36490113ed8fa15dac83148a.png" height="223" alt="Glama"></a>

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 프로필을 사용하세요.** 일반 프로필로 서버를 실행하지 마십시오 — 에이전트는 브라우저가 접근할 수 있는 모든 것(쿠키 및 저장된 세션 포함)에 접근할 수 있습니다.
- **방문하는 사이트에 주의하세요.** 페이지는 에이전트를 조작하도록 설계된 콘텐츠(프롬프트 인젝션)를 반환할 수 있습니다. 통제하거나 신뢰하는 사이트만 사용하세요.
- **필요한 도구 모듈만 활성화하세요.** 기본 `basic` 프리셋에는 이미 `evaluate_script`가 포함되어 있습니다. `--tool-preset slim`은 이를 제외합니다. `--tool-preset developer`(디버깅, 네트워크, 콘솔, 프로파일러) 및 `--tool-preset mozilla`(권한 컨텍스트)와 같은 상위 프리셋은 에이전트가 할 수 있는 작업을 더 확장합니다.

전체 위험 분석 및 취약점 보고 방법은 [SECURITY.md](https://github.com/mozilla/firefox-devtools-mcp/blob/main/SECURITY.md)를 참조하세요.

## 요구 사항

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

## Claude Code 또는 Codex와 함께 설치 및 사용(npx)

권장: 최신 게시 버전을 실행하려면 `npx`를 사용하세요.

### 옵션 A — CLI

#### Claude Code

```bash
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
```

#### Codex

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

# 인자로 헤드리스 + 뷰포트
codex mcp add firefox-devtools -- \
  npx @mozilla/firefox-devtools-mcp@latest -- --headless --viewport 1280x720

# 또는 환경 변수로
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에 추가:

```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에 추가:

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

```bash
npm run setup
# Claude Code 선택; 스크립트가 올바른 경로에 JSON을 저장합니다
```

## MCP Inspector로 시도하기

```bash
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-modules-and-presets) 참조. (`TOOL_PRESET`)
- `--tools` — 활성화할 도구 모듈의 명시적 목록으로 `--tool-preset`을 완전히 재정의(예: `--tools pages network script`). [도구 모듈 및 프리셋](#tool-modules-and-presets) 참조.
- `--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` 매개변수가 기본 루트 대신 디스크의 아무 곳에나 쓸 수 있게 합니다. [대용량 출력을 디스크에 저장](#saving-bulky-output-to-disk) 및 [SECURITY.md](https://github.com/mozilla/firefox-devtools-mcp/blob/main/SECURITY.md)의 보안 참고 사항 참조. (`UNRESTRICTED_SAVE_PATHS=true`)
- `--log-file` — MCP 서버 로그를 stderr 대신 파일에 기록. 서버 출력을 숨기는 MCP 클라이언트로 세션을 디버깅할 때 유용. 상세 디버그 로그도 포함하려면 `DEBUG=*` 설정. 예: `--log-file /tmp/firefox-mcp.log`

### 도구 모듈 및 프리셋

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

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

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

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

기본값인 `basic`에는 `script`가 포함되므로 `evaluate_script` 도구가 포함됩니다. 이것이 공격 표면에 의미하는 바는 [SECURITY.md](https://github.com/mozilla/firefox-devtools-mcp/blob/main/SECURITY.md#tool-modules-and-presets)를 참조하고, 이를 제외하려면 `--tool-preset slim` 또는 명시적 `--tools` 목록을 사용하세요.

```bash
# 개발자 프리셋 사용(네트워크, 콘솔, 디버깅 및 프로파일러 도구 추가)
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](https://searchfox.org/firefox-main/source/remote/shared/RecommendedPreferences.sys.mjs)를 적용합니다. 이를 건너뛰고 일반 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가 필요합니다.

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

```bash
# 연결된 장치 나열
adb devices

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

# 특정 장치 대상
npx @mozilla/firefox-devtools-mcp --android-device <serial> --android-wipe-app-data

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

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

### 기존 Firefox에 연결

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

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

## 도구 개요

모듈별 전체 도구 목록(설명 및 매개변수 포함, 소스에서 생성됨)은 [docs/tools.md](https://github.com/mozilla/firefox-devtools-mcp/blob/main/docs/tools.md)를 참조하세요.

- Pages: list/new/navigate/select/close/get_page_text(get_page_text는 선택적 `saveTo` 지원)
- Snapshot/UID: take/resolve/clear(take는 선택적 `saveTo` 지원)
- Input: click/hover/fill/drag/upload/form fill/press_key/type_text
- Network: list/get(ID 우선, 필터, 항상 캡처; 둘 다 선택적 `saveTo` 지원)
- Downloads: list_downloads/clear_downloads(항상 캡처), set_download_behavior(allow/deny/default)
- Console: list/clear(list는 선택적 `saveTo` 지원)
- Screenshot: page/by uid(CLI 환경용 선택적 `saveTo` 포함)
- Script: evaluate_script(격리된 영역용 선택적 `sandbox`; 대용량 결과용 선택적 `saveTo`)
- Privileged Context: 권한("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 Management: get_firefox_info, get_firefox_output, restart_firefox
- Firefox Preferences: get_firefox_prefs, set_firefox_prefs(`MOZ_REMOTE_ALLOW_SYSTEM_ACCESS=1` 필요)
- Profiler: profiler_is_active, profiler_start(프리셋 또는 명시적 구성), profiler_stop(다운로드 디렉토리에 프로필 저장)
- Screencast: screencast_start(페이지 뷰포트를 다운로드 디렉토리의 비디오 파일로 기록), screencast_stop(Firefox 154+ 필요)
- Utilities: accept/dismiss dialog, history back/forward, set viewport

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

대용량 도구 출력은 Claude Code와 같은 CLI 클라이언트에서 상당한 컨텍스트를 소비할 수 있습니다. `screenshot_page`, `screenshot_by_uid`, `take_snapshot`, `list_console_messages`, `list_network_requests`, `get_network_request`, `get_page_text`, `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` 도구로 컨텍스트 크기에 영향을 주지 않고 볼 수 있습니다.

## 로컬 개발

```bash
npm install
npm run build

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

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

로컬 개발, 테스트 및 CI에 대한 자세한 내용은 [CONTRIBUTING.md](https://github.com/mozilla/firefox-devtools-mcp/blob/main/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 error -32000: Connection closed
  - **해결책 1** `cmd /c`로 감싸기([세부 정보](https://github.com/modelcontextprotocol/servers/issues/1082#issuecomment-2791786310)):

    ```json
    "mcpServers": {
      "firefox-devtools": {
        "command": "cmd",
        "args": ["/c", "npx", "-y", "@mozilla/firefox-devtools-mcp@latest"]
      }
    }
    ```

  - **해결책 2** `npx`의 절대 경로 사용(설정에 맞게 확장자 — `.cmd`, `.bat`, `.exe` 또는 `.ps1` — 조정):

    ```json
    "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](https://github.com/mozilla/firefox-devtools-mcp/blob/main/CONTRIBUTING.md)를 참조하세요.

## 작성자

[Mozilla](https://www.mozilla.org)에서 유지 관리.

## 라이선스

선택에 따라 [MIT](https://github.com/mozilla/firefox-devtools-mcp/blob/main/LICENSE-MIT) 또는 [Apache 2.0](https://github.com/mozilla/firefox-devtools-mcp/blob/main/LICENSE-APACHE) 중 하나로 라이선스가 부여됩니다.
도구 다운로드
인기

firefox-devtools-mcp
