# خادم 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>

خادم Model Context Protocol لأتمتة Firefox عبر WebDriver BiDi (من خلال Selenium WebDriver). يعمل مع Claude Code وClaude Desktop وCursor وCline وعملاء MCP آخرين.

المستودع: https://github.com/mozilla/firefox-devtools-mcp

> **ملاحظة**: يتطلب خادم MCP هذا تثبيت متصفح Firefox محليًا ولا يمكن تشغيله على خدمات الاستضافة السحابية مثل glama.ai. استخدم `npx @mozilla/firefox-devtools-mcp@latest` للتشغيل محليًا، أو استخدم Docker مع ملف Dockerfile المرفق.

## الأمان

تحمل خوادم 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` لتشغيل أحدث إصدار منشور من npm.

### الخيار أ — سطر الأوامر

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

### الخيار ب — تحرير ملف التكوين

#### Claude Code

أضف إلى mcp_settings.json الخاص بـ Claude Code:

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

### الخيار ج — سكربت مساعد (بناء تطوير محلي)

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

## خيارات سطر الأوامر

يمكنك تمرير علامات أو متغيرات بيئة (الأسماء على اليمين):

- `--firefox-path` — المسار المطلق لملف Firefox الثنائي
- `--headless` — التشغيل بدون واجهة مستخدم (`FIREFOX_HEADLESS=true`)
- `--viewport 1280x720` — حجم النافذة الأولي
- `--profile-path` — استخدام ملف تعريف Firefox محدد
- `--firefox-arg` — وسائط Firefox إضافية (قابلة للتكرار)
- `--start-url` — فتح هذا الرابط عند البدء (`START_URL`)
- `--accept-insecure-certs` — تجاهل أخطاء TLS (`ACCEPT_INSECURE_CERTS=true`)
- `--connect-existing` — الاتصال بجلسة Firefox قيد التشغيل بدلاً من إطلاق واحدة جديدة (`CONNECT_EXISTING=true`)
- `--marionette-port` — منفذ Marionette لوضع connect-existing، الافتراضي 2828 (`MARIONETTE_PORT`)
- `--pref name=value` — تعيين تفضيل Firefox عند بدء التشغيل عبر `moz:firefoxOptions` (قابل للتكرار)
- `--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 لنظام 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`. حزم أخرى: `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`)
- `--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
# استخدم الإعداد المسبق developer (يضيف أدوات الشبكة ووحدة التحكم وتصحيح الأخطاء وملف التعريف)
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) التي تعدل سلوك المتصفح للاختبار. اضبط remote.prefs.recommended على false لتخطي تلك والحصول على تكوين أقرب إلى مثيل Firefox عادي.
- remote.log.level=Trace. فعّل سجلات بروتوكول WebDriver التفصيلية في Firefox. سيمرر خادم MCP تلقائيًا مستوى السجل المطابق إلى geckodriver بحيث يسجل كلا الجانبين بنفس مستوى التفصيل.
- app.update.disabledForTesting=false. اسمح لـ Firefox بتنزيل التحديثات وتطبيقها تلقائيًا. لاحظ أن التحديثات قد تقاطع جلستك. يتطلب أيضًا تعيين remote.prefs.recommended=false.

### Firefox لنظام Android

استخدم `--android-device` لأتمتة Firefox الذي يعمل على جهاز Android. يتطلب `adb` في PATH الخاص بك و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 لنظام 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
# ابدأ Firefox مع Marionette وRemote Agent (BiDi)
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 وغيرها.
> فعّل Marionette فقط عندما تحتاج إلى أتمتة MCP، ثم أعد تشغيل Firefox
> بشكل طبيعي بعد ذلك.

## نظرة عامة على الأدوات

راجع [docs/tools.md](https://github.com/mozilla/firefox-devtools-mcp/blob/main/docs/tools.md) للحصول على القائمة الكاملة للأدوات حسب الوحدة، مع
الأوصاف والمعاملات (مولدة من المصدر).

- الصفحات: list/new/navigate/select/close/get_page_text (يدعم get_page_text `saveTo` اختياريًا)
- اللقطة/UID: take/resolve/clear (يدعم take `saveTo` اختياريًا)
- الإدخال: click/hover/fill/drag/upload/form fill/press_key/type_text
- الشبكة: list/get (أولاً بالمعرف، فلاتر، التقاط دائم التشغيل؛ كلاهما يدعم `saveTo` اختياريًا)
- التنزيلات: list_downloads/clear_downloads (التقاط دائم التشغيل), set_download_behavior (allow/deny/default)
- وحدة التحكم: list/clear (يدعم list `saveTo` اختياريًا)
- لقطة الشاشة: page/by uid (مع `saveTo` اختياري لبيئات سطر الأوامر)
- السكربت: evaluate_script (`sandbox` اختياري لبيئة معزولة؛ `saveTo` اختياري للنتائج الكبيرة)
- السياق المميز: list/select للسياقات المميزة ("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: get_firefox_info, get_firefox_output, restart_firefox
- تفضيلات Firefox: get_firefox_prefs, set_firefox_prefs (يتطلب `MOZ_REMOTE_ALLOW_SYSTEM_ACCESS=1`)
- ملف التعريف: profiler_is_active, profiler_start (إعداد مسبق أو تكوين صريح), profiler_stop (يحفظ ملف التعريف في دليل التنزيلات)
- البث الشاشي: screencast_start (يسجل منفذ عرض الصفحة إلى ملف فيديو في دليل التنزيلات), screencast_stop (يتطلب Firefox 154+)
- الأدوات المساعدة: accept/dismiss dialog, history back/forward, set viewport

### حفظ المخرجات الكبيرة على القرص

يمكن أن تستهلك مخرجات الأدوات الكبيرة سياقًا كبيرًا في عملاء سطر الأوامر مثل Claude Code. تقبل أدوات
`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` للكتابة إلى
مواقع عشوائية، بما في ذلك المسارات المطلقة خارج ذلك الدليل.

يمكن بعد ذلك عرض الملفات المحفوظة على سبيل المثال باستخدام أداة `Read` الخاصة بـ Claude Code دون التأثير على حجم السياق.

## التطوير المحلي

```bash
npm install
npm run build

# التشغيل مع Inspector ضد البناء المحلي
npx @modelcontextprotocol/inspector node dist/index.js --headless --viewport 1280x720

# أو التشغيل في وضع التطوير مع إعادة التحميل السريع
npm run inspector:dev
```

راجع [CONTRIBUTING.md](https://github.com/mozilla/firefox-devtools-mcp/blob/main/CONTRIBUTING.md) لمزيد من التفاصيل حول التطوير المحلي والاختبار وCI.

## استكشاف الأخطاء وإصلاحها

- Firefox غير موجود: مرر `--firefox-path "/Applications/Firefox.app/Contents/MacOS/firefox"` (macOS) أو المسار الصحيح على نظام التشغيل الخاص بك.
- التشغيل الأول بطيء: يقوم Selenium بإعداد جلسة BiDi؛ التشغيلات اللاحقة أسرع.
- UIDs قديمة: يظل UID صالحًا حتى تتم إزالة عنصره أو تنقل الصفحة؛ التقط لقطة جديدة (`take_snapshot`) عندما تبلغ أداة UID أن أحدها اختفى.
- 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"]
      }
    }
    ```

## الإصدارات

- API قبل 1.0: تبدأ الإصدارات من `0.x`. استخدم `@latest` مع npx لأحدث إصدار.

## المساهمة

راجع [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
