خادم Firefox DevTools MCP

خادم 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 للحصول على تفصيل كامل للمخاطر وكيفية الإبلاغ عن الثغرات الأمنية.

المتطلبات

• Node.js ≥ 20.19.0
• Firefox 100+ مثبت (يتم اكتشافه تلقائيًا، أو مرر --firefox-path)

التثبيت والاستخدام مع Claude Code أو Codex (npx)

موصى به: استخدم npx لتشغيل أحدث إصدار منشور من npm.

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

Claude Code

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

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:

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

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

npm run setup
# اختر Claude Code؛ يحفظ السكربت JSON في المسار الصحيح

جرّبه مع 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

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

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

• --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_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 لنظام 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 بالكتابة في أي مكان على القرص بدلاً من الجذور الافتراضية. راجع حفظ المخرجات الكبيرة على القرص وملاحظة الأمان في 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 لفهم ما يعنيه ذلك لسطح الهجوم، واستخدم --tool-preset slim أو قائمة --tools صريحة لإزالته.

# استخدم الإعداد المسبق 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 التي تعدل سلوك المتصفح للاختبار. اضبط 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 إضافة خيار إلى geckodriver للاحتفاظ ببيانات التطبيق الحالية.

# عرض الأجهزة المتصلة
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 لأتمتة جلسة التصفح الحقيقية الخاصة بك، مع ملفات تعريف الارتباط وعمليات تسجيل الدخول وعلامات التبويب المفتوحة سليمة:

# ابدأ 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 للحصول على القائمة الكاملة للأدوات حسب الوحدة، مع الأوصاف والمعاملات (مولدة من المصدر).

• الصفحات: 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 دون التأثير على حجم السياق.

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

npm install
npm run build

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

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

راجع 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 (التفاصيل):

    root@kitploit:~

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

  • الحل 2 استخدم المسار المطلق إلى npx (اضبط الامتداد — .cmd, .bat, .exe, أو .ps1 — ليطابق إعدادك):

    root@kitploit:~

    "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 لكيفية تقديم المشكلات وتشغيل الاختبارات والعمل على المشروع محليًا.

المؤلف

يُصان بواسطة Mozilla.

الترخيص

مرخص بموجب إما MIT أو Apache 2.0 حسب اختيارك.