دليل MCP في Claude Code: أضِف الخوادم بالطريقة الصحيحة
اربط Context7 أو Playwright أو أي خادم MCP بـ Claude Code — وسائل النقل، النطاقات، ملف .mcp.json، مفاتيح API، ولوحة /mcp، في جولة مصوّرة واحدة.
الخلاصة السريعة
- أمر واحد يثبّت أي خادم: claude mcp add name -- npx -y @scope/package للخوادم المحلية، أو claude mcp add --transport http name url للبعيدة.
- ثلاثة وسائل نقل: stdio يشغّل أمرًا على جهازك، وSSE هو الشكل البعيد القديم، وstreamable HTTP هو الخيار البعيد الحديث.
- ثلاثة نطاقات تحدد من يحصل على الخادم: local (لأنت وحدك)، وproject (مشترك عبر .mcp.json)، وuser (في كل مشاريعك).
- نفّذ /mcp داخل الجلسة لترى الحالة والأدوات؛ أول استدعاء أداة يطلب إذنًا، ويمكنك السماح مرة واحدة أو دائمًا.
Claude Code Tutorial #7 - MCP Servers
القناة: The Net Ninja14:16
Claude Code MCP: How to Add MCP Servers (Complete Guide)
القناة: Leon van Zyl17:58
Model Context Protocol (MCP) — official Claude Code docs
التوثيق: code.claude.com/docs
لقطات الشاشة من فصل The Net Ninja — تسجيل شاشة كامل ونظيف. تفكيك الأوامر والنطاقات وإصلاحات Windows اتبعت شرح Leon van Zyl الأكمل والتوثيق الرسمي.
الإطارات ملك لمبدعيها، وننسبها هنا مع روابط عميقة إلى اللحظات المحددة؛ والنص من إعدادنا.
من الصفر إلى خادمَي MCP عاملَين
الجزء 1 · ما الذي تفتحه خوادم MCP
- 1
ما الذي يمنحه MCP لـ Claude Code
يأتي Claude Code بأدوات مدمجة للملفات والطرفية، لكن كل ما خارج قاعدة الكود يبقى بعيدًا عنه. MCP — بروتوكول سياق النموذج — هو الطريقة القياسية من Anthropic لتوصيل أدوات إضافية: خادم يكشف قدراته، وClaude Code يستدعيها كأي أداة مدمجة.
شريحة الدورة التي تعرّف MCP في سطر واحد.المشاهدة عند 0:52 - 2
اختر الخوادم بحسب العمل
كل خادم يحمل أدواته الخاصة. خادم Supabase يستطيع عرض الجداول ونشر دوال الحافة وتنفيذ SQL؛ وPlaywright يقود متصفحًا حقيقيًا؛ وContext7 يقدّم وثائق أطر العمل المحدّثة. ابدأ بالخادم الذي يلغي أكثر مهمة متكررة لديك.
مثال Supabase: ثلاث أدوات لخدمة خارجية واحدة.المشاهدة عند 1:24 - 3
اعثر على أمر التثبيت في README الخادم
ناشرو الخوادم يضعون في README أمر Claude Code جاهزًا — وContext7 وPlaywright كلاهما يفعل ذلك. أدلة مثل PulseMCP تجعل استطلاع الموجود أسهل قبل أن تلتزم بأي شيء.
README الخاص بـ Playwright MCP يوثّق الميزات والمتطلبات.المشاهدة عند 2:02 - 4
افهم أنواع النقل الثلاثة
التوثيق الرسمي يقسم التثبيت إلى محلي وبعيد. خادم stdio يشغّل أمرًا على جهازك — وهذا هو الافتراضي. خوادم SSE وHTTP نقاط نهاية بعيدة تتصل بها؛ SSE قديم وقد حلّ محله streamable HTTP. صيغة claude mcp add تختلف قليلًا بين الحالات.
صفحة التوثيق التي تقارن stdio المحلي بـ SSE وHTTP البعيدين.المشاهدة عند 3:02
الجزء 2 · أضِف أول خادم
- 5
أضِف Context7 بنطاق project
من الطرفية: claude mcp add context7 --scope project -- npx -y @upstash/context7-mcp. الاسم تختاره أنت، وكل ما بعد الشرطتين هو الأمر المطلوب تشغيله، و--scope project يكتب الخادم في إعدادات المشروع المشتركة بدلًا من إعداداتك الشخصية.
أمر الإضافة الكامل لخادم وثائق Context7.المشاهدة عند 5:22 - 6
اقرأ ملف .mcp.json الناتج
خوادم نطاق project تهبط في ملف .mcp.json بجذر المستودع تحت مفتاح mcpServers. كل مدخل يسجّل النوع — stdio هنا — إضافة إلى الأمر ووسائطه: البنية نفسها التي يستخدمها Cursor وClaude Desktop.
داخل .mcp.json: النوع والأمر والوسائط للخادم من نوع stdio.المشاهدة عند 6:42 - 7
مستخدمو Windows: انتبهوا لبادئة cmd /c
على Windows الأصيل دون WSL، تحتاج أوامر stdio إلى cmd /c قبل npx كي تُغلق الطرفية بشكل نظيف بعد انتهاء الخادم. التوثيق الرسمي ينبّه لذلك في صندوق تحذير، والشرح المصوّر يُظهر التعديل بالضبط.
صندوق التحذير الرسمي لخوادم stdio على Windows.المشاهدة عند 3:24 - 8
تأكد أن الملف وصل إلى مستودعك
بعد إضافة بنطاق project، يظهر .mcp.json في المستكشف كملف جديد غير متتبَّع، جاهز للحفظ في المستودع ليتشاركه زملاؤك بالخوادم نفسها. خوادم النطاق local لا تلمس هذا الملف إطلاقًا.
ملف .mcp.json جديد في جذر المشروع، غير متتبَّع وجاهز للحفظ.المشاهدة عند 8:32 - 9
تفضّل البعيد؟ استخدم نقل HTTP
حين يتصرف stdio المحلي بشكل سيئ، تكون نقطة النهاية البعيدة هي المخرج السريع: claude mcp add --transport http context7 --scope project https://mcp.context7.com/mcp. لا عملية محلية ولا npm — Claude Code يتحدث إلى الرابط مباشرة.
نسخة HTTP من أمر الإضافة تجاه نقطة نهاية Context7.المشاهدة عند 8:36 - 10
تحقق من الاتصال في /mcp
شغّل Claude Code ونفّذ /mcp. كل خادم يظهر بحالته وقائمة أدواته. الفشل تعالجه عادةً إعادة الاتصال المدمجة؛ وإن لم تُحل، فيغطي قسم استكشاف الأخطاء أدناه الأسباب الشائعة.
لوحة /mcp تُظهر context7 متصلًا بأداتَيه.المشاهدة عند 9:22
الجزء 3 · استخدم الخوادم في عمل حقيقي
- 11
استدعِ الخادم بطلب حقيقي
اطلب شيئًا لا تستطيع الأدوات المدمجة فعله وسمِّ الخادم: «قارن أحدث وثائق Tailwind بملف CSS العام عندي — استخدم context7». إرفاق الملف بذكر @ يجعل الإجابة مرتبطة بكودك.
الطلب الذي يستدعي أحدث وثائق Tailwind عبر context7.المشاهدة عند 9:38 - 12
وافق على استدعاء الأداة
في أول تشغيل لأداة الخادم، يطلب Claude Code الإذن. وافق مرة واحدة، أو اختر «السماح دائمًا» للخوادم التي تثق بها فتمر النداءات اللاحقة دون سؤال.
بطاقة الإذن لأداة resolve-library-id من Context7.المشاهدة عند 10:00 - 13
اقرأ الإجابة الموثّقة
تُعيد الأداة الوثائق ذات الصلة — إرشادات متغيرات السمة في Tailwind v4 هنا — مع كلفة التوكنات معروضة، وClaude Code يطبّقها على ملفك. هذا هو الغرض كله: إجابات من وثائق حديثة بدل تخمينات بيانات التدريب.
رد get-library-docs يؤكد إعداد السمة.المشاهدة عند 10:15 - 14
ثبّت العادة في CLAUDE.md
اكتب رمز المربع # لإضافة ذاكرة للمشروع، مثل: «استخدم Context7 للوثائق المحدّثة عند تنفيذ مكتبات أو أطر جديدة». يهبط السطر في CLAUDE.md وتورّثه كل الجلسات اللاحقة.
ذاكرة سطر واحد في CLAUDE.md تجعل Context7 الخيار الافتراضي.المشاهدة عند 10:42 - 15
أضِف خادمًا ثانيًا: Playwright
كرّر النمط لأتمتة المتصفح: claude mcp add playwright --scope project -- cmd /c npx @playwright/mcp@latest — واحذف جزء cmd /c على macOS أو Linux. مستودع واحد، عدة خوادم، ملف إعدادات واحد.
إضافة خادم Playwright MCP بنطاق project.المشاهدة عند 11:22 - 16
شاهده يقود المتصفح
اطلب من Claude Code فتح صفحة وتلخيصها — Playwright ينتقل وينقر ويقرأ ثم يرفع تقريرًا. بوثائق Context7 ومتصفح Playwright، معظم المهام الخارجية صارت على بُعد طلب واحد.
Playwright MCP ينتقل إلى موقع لتلخيصه.المشاهدة عند 12:42
متغيرات البيئة والترويسات ومفاتيح API
الخوادم البعيدة وواجهات API المحمية تحتاج بيانات اعتماد. يأخذها Claude Code كمتغيرات بيئة للخوادم من نوع stdio وكترويسات للبعيدة — دون تعديل ملفات الإعداد يدويًا.
- 1خوادم stdio: claude mcp add myserver -e API_KEY=your-key -e ZONE=your-zone -- npx -y @some/mcp-server — كرّر العلم -e لكل متغير، ومكانه مباشرة بعد اسم الخادم.
- 2خوادم HTTP البعيدة: claude mcp add --transport http myserver https://example.com/mcp --header "Authorization: Bearer your-key" — تُرسل الترويسة مع كل استدعاء أداة.
- 3تذكير بالنطاقات: local يُبقي الخادم لك في هذا المشروع، وproject يشاركه عبر .mcp.json، وuser يثبّته في كل مشاريعك. يُحدَّد بـ -s أو --scope عند الإضافة.
- 4إزالة خادم: claude mcp remove name — وفي نطاق project، احفظ تغيير .mcp.json كي يختفي الخادم عند زملائك أيضًا.
القيم الممرّرة بـ -e تُخزَّن نصًا صريحًا داخل ملف الإعداد. استخدم مفاتيح ضيقة الصلاحيات حيث تسمح الواجهة، ولا تحفظ أبدًا بيانات اعتماد حقيقية في ملف .mcp.json بنطاق project.
حين تُظهر /mcp فشلًا
معظم إخفاقات MCP في Claude Code تعود إلى أسباب قليلة. امشِ على هذه القائمة قبل أن تحذف وتعيد الإضافة.
- 1خطأ Unknown option -y على Windows: بعض الطرفيات تتعثر في علم npm هذا. شغّل أمر الإضافة من PowerShell أو موجه الأوامر، أو احذف -y وأضِف الخادم ثم أعد -y يدويًا إلى مصفوفة args في .mcp.json.
- 2فشل stdio على Windows الأصيل: أضف البادئة cmd /c للأمر — مثل cmd /c npx -y @some/package@latest. بلا WSL هذا إلزامي، والوسم @latest يجنّبك بنيات مخبأ قديمة.
- 3الحالة فشل: افتح /mcp وأعد الاتصال — الإخفاقات العابرة تزول عادةً من المحاولة الثانية. وإن بقيت، تعرض اللوحة موقع سجل الخادم للخطأ الحقيقي.
- 4الخادم غائب في مشروع آخر: هذا هو النطاق يعمل كما صُمم. خوادم نطاق project تسكن في .mcp.json ذلك المستودع؛ وللتفعيل على مستوى الجهاز كله انتقل إلى نطاق user.
- 5الخادم متصل لكنه لا يُستدعى: سمِّه في الطلب — «تحقق من الوثائق عبر context7» — أو أضِف ذاكرة في CLAUDE.md، لأن النماذج بلا توجيه تمدّ يد العادة إلى الأدوات المدمجة المألوفة.
عندما يفشل كل شيء: claude mcp remove name، أعد تشغيل الطرفية، وأضِف الخادم من جديد بالنقل الذي تجربه ويعمل — ونسخة HTTP البعيدة هي الأكثر ثباتًا.