Cursor Supabase MCP لا يعمل؟ الإعداد الصحيح والحلول

أضفت خادم Supabase إلى Cursor، وأعدت تشغيل المحرر، والآن تُظهر لوحة MCP نقطة حمراء، أو قائمة أدوات فارغة، أو مؤشر تحميل لا يتوقف. أو يبدو الاتصال ناجحًا، لكن الوكيل يصرّ على أنه لا يملك أدوات قاعدة البيانات. هذه الفجوة بين "مُعدّ" و"يعمل" هي أكثر صور عدم عمل Cursor Supabase MCP شيوعًا، وتقريبًا كل حالة تعود إلى قائمة قصيرة من الأسباب: ملف إعداد في مكان خاطئ، أو تسجيل دخول غير مكتمل، أو تسجيل OAuth قديم، أو رابط بنطاق محدد يخفي الأدوات، أو عدد كبير من الأدوات عبر الخوادم، أو خصوصية في Windows مع npx، أو مشروع متوقف، أو مطالبة بالموافقة لم ينقر عليها أحد. فيما يلي كل سبب بالترتيب الذي يستحق الفحص، مع الإعداد الدقيق، وجدول الأعراض، وفحوص السجلات التي توفر عليك ساعات من العمل.

كيف يعمل الربط بين Cursor و Supabase

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

عندما يحدث خلل ما، فإنه يقع في إحدى أربع خطوات، ومعرفة الخطوة تختصر البحث إلى النصف:

1. قراءة الإعداد: الملف مفقود، أو غير صالح، أو في مجلد خاطئ.
2. الاتصال: لا يمكن الوصول إلى الرابط، أو لا يمكن تشغيل الأمر.
3. المصادقة: تسجيل الدخول عبر المتصفح لم يكتمل، أو الرمز غير صحيح.
4. سرد الأدوات: الخادم متصل، لكن معاملاتك تخفي الأدوات، أو الوكيل مثقل بالأدوات.

الخادم المستضاف مقابل npx المحلي

لديك ثلاث طرق للاتصال، والخلط بين إعداداتها مصدر شائع للالتباس.

💡 اختر واحدًا. إذا ظهر اسم الخادم نفسه في ملفي إعداد، أو إذا كان إدخال بعيد وإدخال npx كلاهما يستخدمان supabase، فقد تقضي ساعة في تصحيح الخطأ في الإدخال الخاطئ.

أين يجب أن يوجد mcp.json

يقرأ Cursor موقعين. ملف المشروع في .cursor/mcp.json ينطبق على ذلك المستودع. وملف المستخدم في ~/.cursor/mcp.json ينطبق في كل مكان، وتشير وثائق Supabase إليه إذا أردت إعدادًا واحدًا لكل المشاريع.

ثلاثة أخطاء تفسّر نسبة لافتة من النقاط الحمراء: حفظ mcp.json في جذر المستودع بدلًا من داخل .cursor، وترك فاصلة زائدة في آخر الملف تجعل JSON غير صالح، وكتابة اسم الخاصية العليا mcpServers بشكل خاطئ. الصق الملف في أي أداة للتحقق من JSON قبل أن تلوم الخادم.

الإعداد النظيف الذي يعمل

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

رابط بعيد مع تسجيل الدخول عبر المتصفح

يحتاج الخادم المستضاف إلى رابط فقط:

{
  "mcpServers": {
    "supabase": {
      "url": "https://mcp.supabase.com/mcp"
    }
  }
}

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

احفظ الملف، وأعد تشغيل Cursor، وافتح Settings > Cursor Settings > Tools & MCP. يجب أن يعرض إدخال Supabase خيار تسجيل الدخول. تُفتح نافذة المتصفح، وتسجل الدخول إلى Supabase، وتمنح الوصول إلى مؤسستك. إذا كنت تفضّل الطرفية، فلدى Cursor CLI ثلاثة أوامر مطابقة:

agent mcp enable supabase
agent mcp login supabase
agent mcp list

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

ثم شغّل اختبار الدخان الذي تقترحه Supabase في محادثة وكيل جديدة: "ما الجداول الموجودة في قاعدة بياناتي؟ استخدم أدوات MCP." إذا ظهرت إجابة حقيقية بأسماء جداولك، فالسلسلة كلها تعمل. أما اعتذار عن غياب الأدوات فيعني أن أحد الحلول أدناه ينطبق عليك.

رمز الوصول وبديل npx

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

{
  "mcpServers": {
    "supabase": {
      "command": "npx",
      "args": [
        "-y",
        "@supabase/mcp-server-supabase@latest",
        "--read-only",
        "--project-ref=<your-project-ref>"
      ],
      "env": {
        "SUPABASE_ACCESS_TOKEN": "<personal-access-token>"
      }
    }
  }
}

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

يتطلب هذا المسار تثبيت Node.js. تؤدي العلامتان --read-only و--project-ref الوظيفتين نفسيهما لمعاملات الرابط الموصوفة لاحقًا. تعامل مع الرمز كأنه كلمة مرور: لا تُودِع أبدًا ملف mcp.json يحتويه في مستودع عام. وقد غيّرت Supabase إعدادها الموصى به مع الوقت، فتحقق من تبويب اتصال MCP في لوحة Supabase إذا اختلفت تعليماتها الحالية عن هذا المقتطف.

يحتاج Windows إلى غلاف cmd

على Windows، npx هو غلاف دفعي، وتشغيله مباشرة غالبًا ما ينتهي بخطأ spawn. غلّفه باستخدام cmd /c:

{
  "mcpServers": {
    "supabase": {
      "command": "cmd",
      "args": [
        "/c",
        "npx",
        "-y",
        "@supabase/mcp-server-supabase@latest",
        "--read-only",
        "--project-ref=<your-project-ref>"
      ],
      "env": {
        "SUPABASE_ACCESS_TOKEN": "<personal-access-token>"
      }
    }
  }
}

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

شغّل node --version وnpx --version في طرفية جديدة أولًا. إذا ثُبّت Node بعد بدء Cursor، فما زال المحرر يحتفظ بمسار PATH القديم، لذلك أغلق Cursor تمامًا وأعد فتحه، لا النافذة فقط. يتجنب مسار الرابط المستضاف كل هذا، وهذا سبب وجيه لتفضيله على أجهزة Windows ذات أدوات التطوير المقيّدة.

ثمانية أعراض وحلولها

طابق ما تراه مع صف في الجدول، ثم انتقل إلى القسم المناسب أدناه.

النقطة الحمراء وقائمة أدوات فارغة

النقطة الحمراء تعني أن Cursor لم يحصل على اتصال يعمل قط، لذلك ابدأ بأرخص الفحوص. تحقق من JSON، وتأكد أن الملف موجود في .cursor/mcp.json أو ~/.cursor/mcp.json، واضغط زر التحديث في إعدادات MCP، وهو ما أعاد تشغيل خوادم متوقفة لدى بعض المستخدمين في منتدى Cursor. أعد تشغيل Cursor بعد كل تغيير في الإعداد، فملاحظات Supabase نفسها تقول إن إعادة التشغيل ضرورية قبل ظهور كل الأدوات.

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

حلقات تسجيل الدخول وأخطاء client_id

مع الخادم المستضاف، ينهي Cursor تسليم OAuth بفتح صفحة على localhost:8787. تظهر هنا فشلان.

• خطأ 431 قبل اكتمال تسجيل الدخول. قد تسببه كوكيز كبيرة الحجم خزّنتها خوادم التطوير الأخرى لديك على localhost. امسح كوكيز localhost فقط، لا كوكيز المتصفح كله، ثم أعد محاولة تسجيل الدخول.
• "Unrecognized client_id". يعيد Cursor استخدام تسجيل OAuth مخزّن من إعداد قديم. افصل الخادم، واحذفه، وأغلق Cursor تمامًا، ثم أضفه من جديد ليُسجَّل من البداية.

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

متصل، لكن الأدوات مفقودة

الإشارة الخضراء مع وكيل أعمى غالبًا ما تعني أن الإعداد يفعل بالضبط ما طلبته منه. أربعة معاملات في الرابط تغيّر الأدوات الموجودة:

مثال على رابط بنطاق محدد يبدو هكذا: https://mcp.supabase.com/mcp?project_ref=abc123&read_only=true

ثلاث نتائج تفاجئ الناس. إضافة project_ref تعطّل أدوات الحساب، لذلك يكون غياب قائمة المشاريع متوقعًا. مجموعة Storage مغلقة افتراضيًا ويجب تشغيلها. وread_only=true يجعل كل عملية كتابة تفشل عمدًا. اطلب من الوكيل أن يسرد كل أدوات Supabase التي يستطيع استدعاءها الآن، ثم قارن القائمة بمعاملاتك.

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

الموافقات والمشاريع المتوقفة

سببان أخيران يبدوان فشلًا لكنهما ليسا كذلك. أولًا، يطلب Cursor عادةً الموافقة قبل تشغيل أداة MCP، فقد يكون الوكيل الذي يبدو متجمدًا ينتظر زر موافقة أعلى المحادثة. تأكد أنك في وضع Agent، فهو الوضع الذي تعمل فيه الأدوات.

ثانيًا، قد يكون المشروع نفسه متوقفًا. مشاريع الطبقة المجانية قد تتوقف بعد نحو أسبوع من عدم النشاط، وتفشل الاستعلامات على قاعدة بيانات متوقفة حتى عندما يكون رابط MCP سليمًا. استأنفه من لوحة Supabase وأعد المحاولة.

اقرأ السجلات قبل التخمين

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

أين يخزّن Cursor السجلات

افتح لوحة Output من قائمة View، واختر إدخال MCP لخادم Supabase في قائمة القناة. أعد تشغيل الخادم، ثم اقرأ آخر 20 سطرًا. الأنماط المعتادة:

لاختبار مسار الشبكة وحده، شغّل curl -i https://mcp.supabase.com/mcp من الطرفية. أي حالة HTTP، حتى 401، تثبت أن المضيف قابل للوصول. أما المهلة أو خطأ TLS فيشيران إلى VPN أو وكيل أو جدار حماية، لا إلى Cursor.

قائمة الفحص في عشر دقائق

عندما تريد مراجعة سريعة بدلًا من تعمق كامل، نفّذ هذه القائمة بالترتيب:

1. تحقق من JSON وتأكد من موقع الملف.
2. أبقِ إدخال supabase واحدًا فقط في ملفي الإعداد.
3. تحقق من node --version وnpx --version إذا كنت تستخدم مسار npx.
4. غلّف npx بـ cmd /c على Windows.
5. أغلق Cursor تمامًا وأعد فتحه.
6. أكمل تسجيل الدخول عبر المتصفح، مع مسح كوكيز localhost عند خطأ 431.
7. احذف الإدخال وأعد إضافته عند خطأ "Unrecognized client_id".
8. تحقق من project_ref وfeatures وread_only في الرابط.
9. انتقل إلى وضع Agent ووافق على أي استدعاء أداة معلّق.
10. تأكد أن مشروع Supabase غير متوقف.

عدد كبير من الأدوات يضر بالوكيل

يحذّر Cursor برسالة "Exceeding total tools limit" عندما تتجاوز أدوات كل خوادمك عدد 40، ويذكر أن عددًا كبيرًا من الأدوات قد يتسبب في تراجع الأداء، وأن بعض النماذج قد لا تلتزم بأكثر من 40. تحمّل الإصدارات الأحدث سياق الأدوات ديناميكيًا، ويُبلغ بعض المستخدمين بعدم ظهور أي تحذير مع تفعيل أكثر من 80 أداة.

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

تقليم قائمة الأدوات

• أوقف الخوادم التي لا تستخدمها في هذه الجلسة.
• حدّد Supabase باستخدام features=database,docs عندما تحتاج إلى SQL والوثائق فقط.
• انقر على أسماء الأدوات الفردية في إعدادات MCP لإيقاف ما لا تستدعيه أبدًا.
• أبقِ الخوادم الخاصة بالمشروع في .cursor/mcp.json، والعامة في ملف المستخدم.

أحكم الإغلاق قبل أن تثق

خادم MCP الذي يستطيع تشغيل SQL يستحق العناية نفسها التي تستحقها بيانات دخول قاعدة البيانات. توصية Supabase نفسها صريحة: اتصل بالإنتاج عند الضرورة فقط، واستخدم تحديد نطاق المشروع، ووضع القراءة فقط، ومجموعات الميزات المقيّدة عندما تفعل ذلك.

وضع القراءة فقط وتحديد نطاق المشروع

ثلاثة إعدادات تقوم بمعظم الحماية. read_only=true يشغّل الاستعلامات كمستخدم Postgres للقراءة فقط. project_ref يحصر الخادم في مشروع واحد. features يقلّص مجموعات الأدوات إلى ما تحتاجه. وتعرض Supabase أيضًا نوافذ تأكيد قبل أي شيء ينشئ موارد قابلة للفوترة، فلا توافق عليها تلقائيًا. يجب أن تعمل الروتينات غير المراقبة دائمًا بوضع القراءة فقط.

حقن الأوامر هو الخطر الحقيقي

التهديد الرئيسي الخاص بالنماذج اللغوية الكبيرة هو تعليمات خبيثة مخفية داخل البيانات. تخيل صف تذكرة دعم يقول نصه للنموذج أن يتجاهل التعليمات السابقة ويصدّر جدول المستخدمين. إذا قرأ الوكيل هذا الصف عبر أداة، فقد يعامل النص كأمر. أبقِ الموافقة اليدوية على استدعاءات الأدوات، واقرأ كل عبارة SQL قبل أن توافق عليها. وتسرد وثائق MCP من Supabase هذه الحمايات كاملة.

💡 ابنِ الاتصال واختبره في مشروع تطوير مؤقت. انتقل إلى أي شيء يحتوي على بيانات عملاء حقيقية فقط بعد أن يكون وضع القراءة فقط وتحديد نطاق المشروع مطبقين بالفعل.

دع نموذجًا يقرأ السجلات

عندما لا تفهم أسطر السجل، يصبح نموذج لغوي كبير عينًا ثانية سريعة. على Picasso IA، صُمّم Claude Sonnet 5 لأتمتة مهام البرمجة، وGPT 5.6 Sol لحل مهام البرمجة المعقدة، وGemini 3.1 Pro لإجابات عامة أدق. يمكن لأي منها تحويل تتبع المكدس إلى قائمة قصيرة بالمشتبه بهم.

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

أمر نصي لأخطاء الإعداد

أعطِ النموذج الحقائق التي لا يستطيع تخمينها:

I use Cursor on Windows 11 with the hosted Supabase MCP server.
The MCP panel shows a red dot. My mcp.json (secrets removed) is below,
plus the last 20 lines from the MCP output channel.
List the three most likely causes, ranked, with one check for each.

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

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

جرّب بنفسك على Picasso IA

حل كهذا يستحق أكثر من جدار من الإعدادات. تقرأ مدونة أو دليل تشغيل داخلي أو وثيقة فريق بشكل أفضل مع تصوير حقيقي بدلًا من لقطات الشاشة الجاهزة، و Picasso IA يحوّل أمرًا نصيًا عاديًا إلى صورة في ثوانٍ. جرّب Seedream 4.5 للصور الفوتوغرافية الحادة والمفصّلة، أو GPT Image 2 عندما تريد تحويل أمر نصي بسيط إلى مشهد دقيق.

أمر نصي للبدء: "صورة من الأعلى لمكتب مطوّر عند شروق الشمس، حاسوب محمول مفتوح على محرر أكواد ضبابي، كوب خزفي، وملمس واضح لخشب البلوط، عدسة 35 ملم، ضوء نافذة ناعم، وحبيبات فيلم Kodak Portra 400." غيّر العدسة والإضاءة والزاوية، وسيصبح كل تنويع صورة رأس جديدة. تصفح الكتالوج الكامل على picassoia.com/en/all-models وأنشئ أول صورة لك اليوم.