خادم أدوات مطوري Firefox 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 مخصصًا. لا تقم أبدًا بتشغيل الخادم ضد ملف التعريف العادي الخاص بك — فالوكيل لديه حق الوصول إلى كل ما يمكن للمتصفح الوصول إليه، بما في ذلك ملفات تعريف الارتباط والجلسات المحفوظة.
• كن حذرًا بشأن المواقع التي تزورها. يمكن أن تعيد الصفحات محتوى مصممًا للتلاعب بالوكيل (حقن المطالبات). التزم بالمواقع التي تتحكم فيها أو تثق بها.
• قم بتمكين وحدات الأدوات التي تحتاجها فقط. الإعدادات المسبقة الأعلى مثل --tool-preset developer (البرمجة النصية، التصحيح) و--tool-preset mozilla (السياق المميز) توسع بشكل كبير ما يمكن للوكيل فعله.

انظر SECURITY.md للحصول على تفصيل كامل للمخاطر وكيفية الإبلاغ عن الثغرات.

المتطلبات

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

التثبيت والاستخدام مع Claude Code (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

الخيار ب — تحرير ملف إعدادات 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", "@mozilla/firefox-devtools-mcp@latest", "--headless", "--viewport", "1280x720"],
      "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 — فتح عنوان URL هذا عند البدء (START_URL)
• --accept-insecure-certs — تجاهل أخطاء TLS (ACCEPT_INSECURE_CERTS=true)
• --connect-existing — الاتصال بـ Firefox قيد التشغيل بدلاً من تشغيل واحدة جديدة (CONNECT_EXISTING=true)
• --marionette-port — منفذ Marionette لوضع الاتصال بموجود، الافتراضي 2828 ()

وحدات الأدوات والإعدادات المسبقة

يتم تجميع الأدوات في وحدات. يمكنك اختيار الوحدات التي سيتم عرضها إما باستخدام إعداد مسبق مسمى (--tool-preset) أو بقائمة صريحة (--tools). عند تقديم كليهما، يفوز --tools ويتم تجاهل الإعداد المسبق.

الوحدات: pages, snapshot, input, network, console, screenshot, utilities, management, webextension, profiler, screencast, script, debugging, prefs, privileged.

الإعدادات المسبقة (كل منها عبارة عن مجموعة شاملة للإعداد السابق):

• slim — pages, snapshot, input, network, console
• basic (افتراضي) — slim بالإضافة إلى screenshot, utilities, management, webextension, profiler, screencast
• developer — basic بالإضافة إلى ,

# استخدم الإعداد المسبق للمطور (يضيف أدوات البرمجة النصية والتصحيح)
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، والذي تتم إدارته تلقائيًا.

# عرض الأجهزة المتصلة
adb devices

# تشغيل Firefox لنظام Android على الجهاز المتصل الفردي
npx @mozilla/firefox-devtools-mcp --android-device auto

# استهداف جهاز معين
npx @mozilla/firefox-devtools-mcp --android-device <serial>

# استخدام Firefox Nightly بدلاً من ذلك
npx @mozilla/firefox-devtools-mcp --android-device <serial> --android-package org.mozilla.fenix

يتم التعامل مع إعادة توجيه المنفذ بين المضيف والجهاز تلقائيًا بواسطة geckodriver.

الاتصال بـ Firefox الموجود

استخدم --connect-existing لأتمتة جلسة التصفح الحقيقية الخاصة بك، مع ملفات تعريف الارتباط، وتسجيلات الدخول، وعلامات التبويب المفتوحة سليمة:

# تشغيل Firefox مع Marionette ووكيل الوصول عن بُعد (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 بشكل طبيعي بعد ذلك.

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

• الصفحات: قائمة/جديدة/تنقل/تحديد/إغلاق
• اللقطة/UID: أخذ/حل/مسح (يدعم saveTo اختياري)
• الإدخال: نقر/تحويم/ملء/سحب/رفع/ملء نموذج
• الشبكة: قائمة/الحصول (أولوية-ID، عوامل تصفية، التقاط دائم التشغيل)
• التنزيلات: list_downloads/clear_downloads (التقاط دائم التشغيل)، set_download_behavior (السماح/الرفض/الافتراضي)
• وحدة التحكم: قائمة/مسح
• لقطة شاشة: صفحة/بواسطة uid (مع saveTo اختياري لبيئات CLI)
• البرمجة النصية: evaluate_script (مع saveTo اختياري للنتائج الضخمة)
• السياق المميز: قائمة/تحديد سياقات مميزة ("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
• الملف الشخصي للأداء: profiler_is_active، profiler_start (إعداد مسبق أو تكوين صريح)، profiler_stop (يحفظ الملف الشخصي في دليل التنزيلات)
• البث الشاشة: screencast_start (يسجل منفذ عرض الصفحة إلى ملف فيديو في دليل التنزيلات)، screencast_stop (يتطلب Firefox 154+)
• الأدوات المساعدة: قبول/رفض مربع الحوار، الرجوع/التقدم في التاريخ، تعيين منفذ العرض

حفظ المخرجات الضخمة على القرص

يمكن أن تستهلك مخرجات الأدوات الكبيرة سياقًا كبيرًا في عملاء CLI مثل Claude Code. تقبل أدوات screenshot_page و screenshot_by_uid و take_snapshot و list_console_messages و list_network_requests و get_network_request و 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 قديمة بعد التنقل: التقط لقطة جديدة (take_snapshot) قبل استخدام أدوات UID.
• Windows 10: خطأ أثناء الاكتشاف لخادم MCP 'firefox-devtools': خطأ MCP -32000: تم إغلاق الاتصال

  • الحل 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"]
      }
    }
    

الإصدارات

• واجهة برمجة التطبيقات قبل الإصدار 1.0: تبدأ الإصدارات من 0.x. استخدم @latest مع npx للحصول على أحدث إصدار.

المساهمة

انظر CONTRIBUTING.md لكيفية تقديم المشكلات وتشغيل الاختبارات والعمل على المشروع محليًا.

المؤلف

تم الصيانة بواسطة Mozilla.

الترخيص

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