إعداد MCP في Cursor: mcp.json والإعدادات وسوق الإضافات

تلصق مقطعًا في ملف إعدادات، وتعيد تشغيل المحرر، فيظهر الخادم الجديد وبجانب اسمه نقطة حمراء. هذه اللحظة هي سبب أهمية إعداد MCP في Cursor بشكل صحيح. يتيح بروتوكول سياق النموذج (Model Context Protocol) لوكيل Cursor استدعاء أدوات خارجية، من المتصفح إلى قاعدة البيانات إلى أداة توليد الصور، لكن ذلك لا يعمل إلا إذا كان الاتصال مضبوطًا بشكل صحيح. يتبع هذا المقال المسار خطوة بخطوة. سترى مكان mcp.json، وكيفية كتابة الإدخالات المحلية والبعيدة، وأي مفاتيح تقع في الإعدادات، وكيف يثبّت السوق الخوادم بنقرة واحدة، وما الذي يجب فحصه عند حدوث عطل. كل إعداد وارد أدناه يستخدم أسماء الحقول من وثائق Cursor الرسمية، ولا يُحفظ أي سر داخل الملف.

ما الذي تفعله MCP داخل Cursor

MCP بروتوكول مفتوح يمنح عميل الذكاء الاصطناعي طريقة موحدة للتواصل مع برامج خارجية. Cursor هو العميل. وكل برنامج تربطه يُسمّى خادمًا، وكل خادم يعرض أدوات يستطيع الوكيل استدعاءها أثناء المحادثة: قراءة ملف، أو الاستعلام من قاعدة بيانات، أو فتح صفحة ويب، أو إنشاء تذكرة، أو توليد صورة.

الخوادم والأدوات والوكيل

فكّر في ثلاث طبقات. الوكيل يحدد ما طلبته. الخادم يعلن عمّا يستطيع فعله. الأداة إجراء واحد له اسم ووصف ومجموعة من المدخلات. حين تطلب من Cursor معرفة سبب إرجاع نقطة نهاية للخطأ 500، يقرأ الوكيل قائمة الأدوات، ويختار المناسب منها، ويطلب إذنك قبل تشغيلها.

تترتب على ذلك نتيجتان عمليتان:

• عدد أكبر من الخوادم ليس أفضل. كل أداة مفعّلة تضيف وصفها إلى السياق الذي يقرؤه الوكيل، لذلك تجعل دزينة من الخوادم غير المستخدمة الإجابات أبطأ والاختيارات أسوأ.
• الأسماء مهمة. التسميات الواضحة مثل github أو project-files تجعل نوافذ الموافقة سهلة القراءة لاحقًا.

💡 ابدأ بخادم أو اثنين تستخدمهما كل يوم. أضف البقية عندما تتطلبها مهمة حقيقية.

هذا ما يبدو عليه الأمر في العمل اليومي. يتيح خادم المتصفح للوكيل فتح موقع الاختبار الخاص بك، والتنقل عبر عملية الدفع، والإبلاغ عمّا تعطّل. ويتيح خادم GitHub له قراءة مشكلة، وإيجاد الكود المرتبط بها، وصياغة نص طلب الدمج. ويتيح خادم قاعدة البيانات التحقق من صف قبل أن يقترح ترحيلًا. وفي كل حالة يتوقف الوكيل عن التخمين ويبدأ بقراءة بيانات حقيقية، وهذا هو سبب قضاء عشر دقائق في الإعداد كله.

خادم محلي أم بعيد

يدعم Cursor ثلاث طرق نقل، والاختيار بينها يحدد طريقة كتابة الإدخال في mcp.json.

خادم stdio هو الأبسط: يشغّل Cursor أمرًا مثل npx ويتواصل معه عبر الإدخال والإخراج القياسيين. أما الخادم البعيد فهو مجرد عنوان URL. أنت تثق بالمزوّد في تشغيله، وغالبًا ما تسجّل الدخول عبر المتصفح باستخدام OAuth بدلًا من لصق رمز وصول.

مكان ملف mcp.json

يقرأ Cursor تعريفات MCP من ملف JSON اسمه mcp.json. يوجد للملف مكانان، ويمكنك استخدامهما معًا.

الملف العام أو ملف المشروع

في Windows يكون مجلد المستخدم الرئيسي هو ملف تعريف المستخدم، لذلك يقع الملف العام في C:\Users\YourName\.cursor\mcp.json.

يدمج Cursor الملفين. أعطِ الخوادم أسماء مختلفة في كل منهما حتى لا تتساءل أبدًا أي تعريف يعمل. لا ترفع ملف المشروع إلى المستودع إلا إذا كان خاليًا من الأسرار، واستخدم المتغيرات لأي بيانات خاصة.

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

تشريح الإدخال

يحتوي كل ملف على كائن واحد في المستوى الأعلى اسمه mcpServers. داخله، يكون اسم كل خاصية هو تسمية أحد الخوادم، والقيمة تحدد طريقة الوصول إليه.

يستخدم إدخال stdio الحقول command وargs وenv وenvFile. ويستخدم الإدخال البعيد الحقلين url وheaders. افصل بين الشكلين: إدخال واحد لطريقة نقل واحدة.

خادمك الأول خطوة بخطوة

أربع خطوات تكفي تقريبًا في كل الحالات: أنشئ الملف، وأضف إدخالًا، واحفظ، ثم تحقق من النتيجة في الإعدادات. يُظهر المثالان التاليان إدخالًا محليًا وآخر بعيدًا.

إضافة خادم محلي

1. أنشئ ~/.cursor/mcp.json إذا لم يكن موجودًا بعد.
2. الصق الإدخال أدناه.
3. احفظ الملف. يلتقط Cursor التغيير عادةً تلقائيًا. إذا لم يظهر الخادم، أغلق Cursor وأعد فتحه.

{
  "mcpServers": {
    "project-files": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "${workspaceFolder}"]
    }
  }
}

نسخ الأمر النصي

يسمح العلم -y بتثبيت الحزمة عبر npx دون أن يسأل. ويوجّه المتغير ${workspaceFolder} الخادم إلى المشروع المفتوح، فلا يصل إلا إلى الملفات الموجودة داخل ذلك المجلد.

إضافة خادم بعيد

يستبدل الإدخال البعيد command وargs بحقل url. يتصل هذا المثال بالخادم المستضاف لـ GitHub ويقرأ الرمز من متغير بيئة.

{
  "mcpServers": {
    "github": {
      "url": "https://api.githubcopilot.com/mcp/",
      "headers": {
        "Authorization": "Bearer ${env:GITHUB_TOKEN}"
      }
    }
  }
}

نسخ الأمر النصي

الخوادم التي تدعم OAuth لا تحتاج إلى أي ترويسة. يفتح Cursor نافذة متصفح عند أول استخدام، فتوافق على الوصول، ويُحفظ تسجيل الدخول للجلسات اللاحقة. وإذا قدّم لك المزوّد بدلًا من ذلك معرّف عميل ومفتاح سري ثابتين، يقبل Cursor كائن auth يحتوي على CLIENT_ID وCLIENT_SECRET وscopes. أما في تطبيق سطح المكتب فسجّل http://localhost:8787/callback عنوان إعادة التوجيه.

المتغيرات تُبقي الأسرار بعيدة

يوسّع Cursor هذه المتغيرات داخل command وargs وenv وurl وheaders:

• ${env:NAME} يقرأ متغير بيئة.
• ${userHome} هو مجلد المستخدم الرئيسي.
• ${workspaceFolder} هو جذر المشروع.
• ${workspaceFolderBasename} هو اسم مجلد المشروع.
• ${pathSeparator} أو ${/} يعطي الشرطة المائلة المناسبة لنظام التشغيل.

يمكن لخادم محلي يحتاج إلى عنوان قاعدة بيانات ومسار سكربت أن يجمع بينهما:

{
  "mcpServers": {
    "notes-db": {
      "command": "node",
      "args": ["${userHome}${/}tools${/}notes-server${/}index.js"],
      "env": { "DB_URL": "${env:NOTES_DB_URL}" },
      "envFile": "${workspaceFolder}/.env"
    }
  }
}

نسخ الأمر النصي

💡 لا تلصق رمزًا حقيقيًا أبدًا في ملف ستضيفه إلى المستودع. أشر إلى متغير بيئة، وأضف .env إلى .gitignore.

الإعدادات والمفاتيح والموافقات

افتح Cursor Settings وابحث عن Tools & MCP. تعرض الإصدارات الحديثة الخوادم نفسها أيضًا تحت Customize في الشريط الجانبي. هذه غرفة التحكم بكل ما كتبته في mcp.json.

تشغيل الخوادم وإيقافها

لكل خادم مفتاح تشغيل وعدد أدوات. الخادم السليم يعرض أدواته، والخادم المتعطل يُظهر حالة خطأ. ثلاثة فحوص تكشف الحالة بنظرة سريعة:

• مفتاح التشغيل مفعّل.
• عدد الأدوات أكبر من صفر.
• لا توجد مؤشرات خطأ بجانب الاسم.

عطّل الخوادم التي لا تحتاجها لمهمة معينة بدلًا من حذفها. يبقى الإدخال في الملف، وإعادة تفعيله تستغرق ثانية. وهي أيضًا أسرع طريقة لخفض حمل السياق قبل إعادة هيكلة طويلة.

موافقة الأدوات وأوضاع التشغيل

يطلب Cursor افتراضيًا الموافقة قبل تشغيل أي أداة MCP. ترى اسم الأداة ووسائطها، ثم تقبل أو ترفض. تتبع أدوات MCP قواعد وضع التشغيل نفسها المطبّقة على أوامر الطرفية، لذلك إذا كان وضعك يشغّل الإجراءات المدرجة في القائمة البيضاء فورًا، فستعمل أدوات MCP المدرجة في القائمة البيضاء فورًا أيضًا.

💡 اسمح بالأدوات التي تقرأ فقط مثل البحث والسرد والجلب. أبقِ الموافقة مفعّلة لأي شيء يكتب أو يحذف أو ينشر أو ينفق المال.

التثبيت من السوق بنقرة واحدة

كتابة JSON يدويًا تعمل، لكن معظم الناس يبدأون من السوق. تتوفر القوائم على cursor.com/marketplace وعلى cursor.directory.

ما الذي يفعله زر Add to Cursor

لكل قائمة زر Add to Cursor. يؤدي النقر عليه إلى فتح Cursor، ثم يطلب منك التأكيد، ويكتب الإدخال في ~/.cursor/mcp.json العام لديك. وإذا احتاج الخادم إلى OAuth، يوجّهك Cursor بعدها إلى صفحة تسجيل الدخول الخاصة بالمزوّد.

بعد ذلك، افتح قائمة MCP وتحقق من عدد الأدوات. الإدخال عبارة عن JSON عادي، لذلك يمكنك تعديله لاحقًا: أعد تسميته، أو أضف قيمة env، أو انقله إلى ملف مشروع.

افحص قبل التثبيت

يعمل الخادم بصلاحياتك، لذلك يستحق التثبيت بنقرة واحدة عشر ثوانٍ من الحذر.

• تحقق من الناشر. فضّل الخوادم الصادرة عن الخدمة نفسها أو عن مشروع له كود مصدري عام.
• اقرأ الأمر. npx يحمّل كودًا من سجل ويشغّله على جهازك.
• اقرأ قائمة الأدوات. خادم ملاحظات يطلب وصولًا إلى الطرفية علامة تحذير.
• ثبّت الإصدارات باستخدام package@version عندما يكون الاستقرار أهم من التحديثات.
• فضّل الخوادم البعيدة من مزوّد تثق به وسجّل الدخول إليه عبر OAuth.

إذا لم تكن متأكدًا من الخادم الذي تضيفه أولًا، تطابق هذه القائمة القصيرة أكثر المهام اليومية شيوعًا:

إصلاح خادم لا يبدأ العمل

معظم الأعطال تأتي من خمسة أو ستة أسباب. ابدأ بالسجلات، ثم طابق العرض بالسبب.

اقرأ سجلات MCP

افتح لوحة Output بالاختصار Cmd+Shift+U على Mac أو Ctrl+Shift+U على Windows وLinux، ثم اختر MCP Logs من القائمة المنسدلة. يسجّل السجل تهيئة الخوادم واستدعاءات الأدوات ورسائل الخطأ. اقرأ الخطأ الأول، لا الأخير. فالأسطر اللاحقة غالبًا آثار جانبية.

ست أعطال شائعة

حين لا تنطبق أي من هذه الصفوف، شغّل الخادم يدويًا. انسخ command وargs من الإدخال إلى الطرفية، مع قيم البيئة نفسها، وراقب ما يطبعه. إذا فشل هناك، فالمشكلة في الخادم أو في تثبيته، لا في Cursor. وإذا عمل بشكل جيد، فقارن PATH والمتغيرات في الطرفية بما يمرره Cursor عبر env، وألقِ نظرة أخرى على السجل بحثًا عن أول سطر يذكر الخادم باسمه.

إقران MCP بأدوات PicassoIA

الاتصال نصف العمل فقط. تساعد ثلاث ميزات في PicassoIA في ما حوله.

صياغة الإعدادات ومراجعتها. يستطيع النموذج اللغوي الكبير أن يلاحظ فاصلة زائدة في النهاية، ويشرح خطأ من سجلات MCP، ويحوّل مقطع تثبيت من README إلى إدخال Cursor. على PicassoIA يمكنك تشغيل Claude Sonnet 5 أو GPT 5.6 Sol أو Kimi K2.6 أو Gemini 3.5 Flash من مكان واحد، ومقارنة طريقة قراءة كل منها للخطأ نفسه. استبدل كل رمز بعنصر نائب قبل لصق أي إعداد.

صور للوثائق وملفات README. تبدو صفحات الإعداد أفضل مع صورة رأس واضحة. يحوّل Seedream 4.5 وFlux 2 Pro وGPT Image 2 أمرًا نصيًا إلى صورة فوتوغرافية، ويمكن لتحويل الصورة إلى فيديو أن يحوّل صورة ثابتة إلى مقطع قصير لسجل التغييرات أو منشور على وسائل التواصل.

اتصال MCP خاص به. تقدّم PicassoIA واجهة API على https://api.picassoia.com/v1 واتصالات MCP تُدار من حسابك، تشمل توليد الصور وتعديل الصور وتوليد الفيديو مع الصوت. يمكن تشغيل خمس عمليات تنبؤ كحدّ أقصى في الوقت نفسه لكل حساب، وهي مشتركة بين التوكنات واتصالات MCP، لذا ستنتظر الجلسة التي ترسل طلبات كثيرة في قائمة انتظار. يظهر عنوان الخادم داخل حسابك، لذلك لا يعرض هذا المقال عنوانًا. بعد الحصول عليه، يتّبع الإدخال البنية نفسها الموجودة في url، مثل مثال github أعلاه. تحقّق من صفحة خطتك لتتأكد من المستويات التي تشمل اتصالات MCP قبل أن تبني عليها سير عمل.

أنشئ صورك الخاصة بعد ذلك

اختر خادمًا واحدًا من هذا المقال، وأضفه اليوم، ووافق بنفسك على أول استدعاء لأداة. ثم افتح Picasso IA وولّد صورة رأس لملاحظات إعدادك: صورة لمكتبك، أو خلفية هادئة لمخطط، أو مقطعًا قصيرًا لمنشور إصدار. جرّب ثلاثة أوامر نصية مختلفة، وقارن النتائج، واحتفظ بالنتيجة التي تناسب صفحتك. قائمة النماذج الكاملة موجودة على picassoia.com/en/all-models.