/ الدليل / الملعب / Puppeteer
← كل الخوادم ↗ GitHub
● رسمي modelcontextprotocol ⚡ فوري

Puppeteer

بواسطة modelcontextprotocol · modelcontextprotocol/servers-archived

متصفح Chrome بدون واجهة رسومية في MCP واحد — التنقل والتقاط لقطات شاشة والنقر والملء. أبسط من Playwright عندما تحتاج فقط إلى Chromium.

MCP مرجعي مؤرشف لكن لا يزال يعمل من Anthropic. يقود Chromium بدون واجهة رسومية عبر Puppeteer: التنقل والتقاط لقطات الشاشة والنقر والملء والاختيار والتحويم والتقييم الاعتباطي للصفحة. بدون مميزات شجرة الإمكانية — تعمل مع محددات CSS. استخدم هذا عندما يبدو Playwright معقداً جداً.

▶ شاهد العرض 📦 التثبيت 💡 حالات الاستخدام

لماذا تستخدمه

الميزات الأساسية

عرض مباشر

كيف يبدو في الممارسة

puppeteer.replay ▶ جاهز
0/0

التثبيت

اختر العميل

~/Library/Application Support/Claude/claude_desktop_config.json  · Windows: %APPDATA%\Claude\claude_desktop_config.json
{
  "mcpServers": {
    "puppeteer": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-puppeteer"
      ]
    }
  }
}

افتح Claude Desktop → Settings → Developer → Edit Config. أعد التشغيل بعد الحفظ.

~/.cursor/mcp.json · .cursor/mcp.json
{
  "mcpServers": {
    "puppeteer": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-puppeteer"
      ]
    }
  }
}

يستخدم Cursor نفس مخطط mcpServers مثل Claude Desktop. إعدادات المشروع أولى من الإعدادات العامة.

VS Code → Cline → MCP Servers → Edit
{
  "mcpServers": {
    "puppeteer": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-puppeteer"
      ]
    }
  }
}

انقر على أيقونة MCP Servers في شريط Cline الجانبي، ثم "Edit Configuration".

~/.codeium/windsurf/mcp_config.json
{
  "mcpServers": {
    "puppeteer": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-puppeteer"
      ]
    }
  }
}

نفس الصيغة مثل Claude Desktop. أعد تشغيل Windsurf لتطبيق التغييرات.

~/.continue/config.json
{
  "mcpServers": [
    {
      "name": "puppeteer",
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-puppeteer"
      ]
    }
  ]
}

يستخدم Continue مصفوفة من كائنات الخادم بدلاً من خريطة.

~/.config/zed/settings.json
{
  "context_servers": {
    "puppeteer": {
      "command": {
        "path": "npx",
        "args": [
          "-y",
          "@modelcontextprotocol/server-puppeteer"
        ]
      }
    }
  }
}

أضف إلى context_servers. يعيد Zed التحميل تلقائيًا عند الحفظ.

claude mcp add puppeteer -- npx -y @modelcontextprotocol/server-puppeteer

أمر من سطر واحد. تحقق باستخدام claude mcp list. احذف باستخدام claude mcp remove.

حالات الاستخدام

استخدامات عملية: Puppeteer

التقاط لقطات شاشة لقائمة من عناوين URL لتدقيق بصري

👤 فريق ضمان الجودة، المصممون، مديرو المحتوى ⏱ ~10 min beginner

متى تستخدمه: لديك قائمة من الصفحات وتحتاج إلى فحصها جميعاً بعد تغيير.

الخطوات
  1. التنقل والالتقاط
    لكل عنوان URL في [list]، تنقل، انتظر التحميل، التقط لقطة شاشة بملء الصفحة باسم <slug>.png.✓ تم النسخ
    → تم حفظ N لقطات شاشة
  2. المقارنة مع خط الأساس (اختياري)
    قارن كل لقطة شاشة مع الملف المطابق في ./baseline/. حدّد أي لقطة تختلف بأكثر من 5% اختلاف بكسل.✓ تم النسخ
    → قائمة الصفحات المتغيرة
  3. ملخص النتائج
    اكتب ملخصاً بفقرة واحدة: كم صفحة، كم تغيرت، أي منها قد تحتاج إلى مراجعة.✓ تم النسخ
    → حالة سريعة يمكنك لصقها في وصف PR

النتيجة: مجموعة لقطات شاشة جاهزة للخط الأساسي مع تقرير فرق، بدون إعداد خط أنابيب انحدار بصري.

المزالق
  • المحتوى الديناميكي (التواريخ، لافتات A/B) يُظهر فروقات خاطئة — أضف puppeteer_evaluate لإخفاء تلك العناصر عبر CSS قبل لقطة الشاشة
اجمعها مع: filesystem

ملء نموذج بشكل متكرر ببيانات الاختبار

👤 مهندسو ضمان الجودة، مطورو خلفية يختبرون تدفقات الإدخال ⏱ ~15 min intermediate

متى تستخدمه: تحتاج إلى اختبار نموذج مع 20 متغيراً من الإدخال للتحقق من التحقق.

المتطلبات الأساسية
  • عنوان بيئة الاختبار — لا تعمل أبداً ضد الإنتاج — قم بإعداد مثيل إعداد
الخطوات
  1. التنقل إلى النموذج
    افتح https://staging.app/signup. التقط لقطة شاشة للتأكيد.✓ تم النسخ
    → تم تحميل الصفحة، النموذج مرئي
  2. إرسال حالات الاختبار
    لكل حالة اختبار [list: {email, password, expected_error}]، املأ الحقول، انقر فوق إرسال، التقط نص عنصر رسالة الخطأ.✓ تم النسخ
    → بالفعل مقابل المتوقع لكل حالة
  3. الإبلاغ عن عدم المطابقة
    ملخص: أي حالات نجحت، أي فشلت، ما كان الفجوة. التقط لقطة شاشة لكل فشل.✓ تم النسخ
    → تقرير اختبار مع الأدلة

النتيجة: تغطية التحقق بما يتجاوز ما تكتبه في مواصفة Playwright، في 10 دقائق.

المزالق
  • حالة النموذج السابقة تستمر بين التشغيلات — استدعِ puppeteer_navigate إلى عنوان URL جديد بين الحالات، أو امسح الحقول بوضوح باستخدام puppeteer_fill المستند إلى المحدد بتمرير سلسلة فارغة

البحث عن الصور المكسورة أو المفقودة على صفحة

👤 محافظو المحتوى/الوثائق ⏱ ~10 min intermediate

متى تستخدمه: بعد الهجرة أو بعد تغيير CMS — الصور المكسورة شائعة ومحرجة.

الخطوات
  1. تحميل الصفحة
    افتح <URL>. انتظر ثانيتين لصور التحميل البطيء.✓ تم النسخ
    → تم تحميل الصفحة
  2. البحث عن الصور المكسورة عبر التقييم
    قم بتشغيل page.evaluate لإرجاع كل <img> حيث naturalWidth === 0 — تلك فشلت في التحميل. أرجع src و alt لكل واحدة.✓ تم النسخ
    → قائمة مصادر الصور المكسورة
  3. كرر عبر الموقع
    كرر لهذه 20 عنوان URL. أخرج CSV للصفحة، broken-img-src، alt-text.✓ تم النسخ
    → CSV قابل للتنفيذ

النتيجة: قائمة إصلاح محددة للصور المكسورة مع الصفحة التي تظهر فيها.

المزالق
  • لم يتم تفعيل الصور المحملة بطريقة كسولة بعد — مرر الصفحة أولاً باستخدام window.scrollTo(0, document.body.scrollHeight) عبر التقييم، ثم انتظر وتحقق
اجمعها مع: filesystem

التركيبات

اجمعها مع خوادم MCP أخرى لتحقيق نتائج x10

puppeteer + filesystem

التقط كل صفحة وحفظها كملفات صور للمراجعة

افتح كل عنوان URL في urls.txt، التقط لقطة شاشة بملء الصفحة، حفظ إلى ./audit/<slug>.png.✓ تم النسخ
puppeteer + sentry

أعد إنتاج خطأ تم الإبلاغ عنه من Sentry بإعادة تشغيل مسار المستخدم

مسألة Sentry WEB-3a91 لها breadcrumbs يوضح أن المستخدم نقر فوق .checkout-btn ثم ملأ #card-number. أعد إنتاج ذلك في Puppeteer والتقط وحدة التحكم.✓ تم النسخ

الأدوات

ما يوفره هذا الـ MCP

الأداةالمدخلاتمتى تستدعيهاالتكلفة
puppeteer_navigate url افتح أو أعد التوجيه إلى عنوان URL free
puppeteer_screenshot name, selector?, width?, height? التقط الصفحة أو عنصراً محدداً disk space
puppeteer_click selector انقر على عنصر بواسطة محدد CSS free
puppeteer_fill selector, value اكتب في مدخل free
puppeteer_select selector, value اختر خياراً من <select> free
puppeteer_hover selector افتح القوائم أو التلميحات التي تظهر عند التحويم فقط free
puppeteer_evaluate script قم بتشغيل JS عشوائي في سياق الصفحة — الملاذ الأخير لأي شيء لا يمكن للمحددات القيام به free

التكلفة والحدود

تكلفة التشغيل

حصة API
مجاني — التنفيذ المحلي
الرموز لكل استدعاء
لقطات الشاشة ليست رموزاً؛ المحددات/السلاسل صغيرة (~100 رمز لكل استدعاء)
التكلفة المالية
مجاني
نصيحة
استخدم puppeteer_evaluate لاستخراج بالضبط ما تحتاجه كـ JSON — لا تلتقط لقطة شاشة ثم OCR

الأمان

الصلاحيات والأسرار ونطاق الأثر

تخزين بيانات الاعتماد: لا تضع أبداً بيانات اعتماد المستخدم الحقيقي في الأوامر — استخدم حسابات QA مخصصة
نقل البيانات الخارجي: المتصفح يذهب أينما تنقله؛ لا شيء لناشر MCP

استكشاف الأخطاء

الأخطاء الشائعة وحلولها

Error: Element not found

العنصر لم يتم عرضه بعد. أضف انتظاراً قصيراً عبر puppeteer_evaluate('await new Promise(r => setTimeout(r, 1000))') أو استخدم محدداً أكثر تحديداً ينتظر بشكل ضمني.

Chromium fails to launch on Linux/Docker

ثبّت التبعيات: apt-get install -y chromium-browser أو استخدم صورة Playwright MCP التي تحتوي على كل شيء مثبّت مسبقاً.

Screenshots are blank

الصفحة لم تُحمّل. بعد التنقل، انتظر عنصراً معروفاً: puppeteer_evaluate("document.querySelector('.main') !== null") في حلقة استطلاع قبل التقاط الشاشة.

البدائل

Puppeteer مقابل البدائل

البديلمتى تستخدمهاالمقايضة
Playwright MCPأي أتمتة متصفح جادة — الخيار الأفضل بصراحةتثبيت أكبر قليلاً، لكن موثوقية أفضل عبر شجرة الإمكانية
Firecrawl MCPتحتاج فقط إلى استخراج المحتوى، وليس التفاعلمستضاف، يكلف أرصدة، لكنه يتعامل مع مكافحة الروبوت بشكل أفضل
browser-tools MCPتريد فحص Chrome الحقيقي الخاص بك (مع الجلسات المسجلة الدخول والإضافات)يتطلب إضافة Chrome؛ حالة استخدام مختلفة تماماً

المزيد

الموارد

📖 اقرأ ملف README الرسمي على GitHub

🐙 تصفح القضايا المفتوحة

🔍 تصفح أكثر من 400 خادم MCP و Skills