إعداد Claude Desktop لملف MCP: موقع الملف وأمثلة JSON والتهيئة

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

ستحصل على الموقع الدقيق لملف claude_desktop_config.json على Windows وmacOS (بما في ذلك فخ MSIX على Windows الذي يرسل تعديلاتك إلى ملف لا يقرؤه أحد)، ومثال JSON جاهز يمكنك لصقه اليوم، وطريقة للتأكد من أن الخادم اتصل فعلًا، وإجراء قصير لاستكشاف الأخطاء وإصلاحها مبني على سجلات MCP. وفي الجزء الأخير درس حول استخدام Claude Sonnet 5 على PicassoIA لتصحيح الإعداد الخاص بك، مع نظرة على ربط أدوات توليد الصور والفيديو بعد أن يعمل كل شيء.

💡 الخلاصة السريعة: الملف هو claude_desktop_config.json، ويحتاج إلى كائن mcpServers على المستوى الأعلى، ويجب أن تكون كل مسارات داخله مطلقة، ويجب إغلاق التطبيق بالكامل وإعادة فتحه بعد كل تعديل.

أين يوجد ملف الإعداد

يقرأ Claude Desktop ملف JSON واحدًا عند التشغيل ليعرف أي خوادم MCP (خوادم Model Context Protocol) يجب أن يشغّلها. لا يوجد الملف قبل أن تفتحه من شاشة الإعدادات أو تنشئه يدويًا، لذا لن يجد التثبيت الجديد شيئًا. ويعتمد موقع الملف على نظام التشغيل، وعلى Windows يعتمد أيضًا على طريقة تثبيت التطبيق.

مسار Windows وفخ MSIX

في التثبيت العادي على Windows يوجد الملف هنا:

%APPDATA%\Claude\claude_desktop_config.json

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

وبعد توسيع المتغيرات يصبح المسار C:\Users\<your name>\AppData\Roaming\Claude\claude_desktop_config.json. اضغط Win+R، والصق الصيغة الأولى، واضغط Enter لفتح المجلد الصحيح.

وهنا الفخ. عندما يُثبَّت Claude Desktop كحزمة MSIX (وهذا ما يحدث مع نسخة متجر Microsoft وبعض تثبيتات WinGet)، يعزل Windows مجلد AppData الخاص بالتطبيق في بيئة افتراضية. وتصف عدة تقارير عامة من المستخدمين النتيجة نفسها: يفتح زر Edit Config الملف العادي %APPDATA%، بينما يقرأ التطبيق نفسه نسخة مدفونة داخل مجلد الحزمة:

%LOCALAPPDATA%\Packages\Claude_pzs8sxrjxfjjc\LocalCache\Roaming\Claude\claude_desktop_config.json

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

إذا عدّلت الملف الأول، تتجاهل الخوادم تعديلاتك دون أي تحذير. ويمكن لفحص سريع عبر PowerShell أن يخبرك بالحالة التي أنت فيها:

Test-Path "$env:LOCALAPPDATA\Packages\Claude_pzs8sxrjxfjjc"

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

إذا طبع الأمر True، فضع كتلة mcpServers في المسار المحزوم، وأعد التشغيل، وتحقق مما إذا ظهر الخادم. قد تتغير أسماء مجلدات الحزمة بين الإصدارات، لذا اعتبر المسار أعلاه نقطة بداية. وإذا لم يطابق ما تراه، فابحث داخل %LOCALAPPDATA%\Packages عن مجلد يبدأ بـ Claude_.

مسار macOS وملاحظات Linux

على Mac يوجد الملف داخل مجلد Library، وهو مخفي في Finder افتراضيًا:

~/Library/Application Support/Claude/claude_desktop_config.json

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

في Finder اختر Go، ثم Go to Folder، والصق ~/Library/Application Support/Claude. ومن Terminal يؤدي open ~/Library/Application\ Support/Claude الغرض نفسه.

لا يوجد إصدار رسمي من Claude Desktop لنظام Linux. وتتبع البنيات التي طوّرها المجتمع عادةً اصطلاح XDG وتقرأ ~/.config/Claude/claude_desktop_config.json، لكن تحقق من ملاحظات البنية التي تستخدمها قبل أن تثق بهذا المسار.

افتحه من الإعدادات

أقل الطرق عرضة للخطأ هو عبر التطبيق نفسه:

1. انقر قائمة Claude في شريط القوائم في النظام (لا الإعدادات داخل نافذة المحادثة).
2. اختر Settings.
3. افتح تبويب Developer في الشريط الجانبي الأيسر.
4. انقر Edit Config.

يُنشئ هذا الملف إذا كان مفقودًا، ويعرضه في مدير الملفات لديك. وفي تثبيت MSIX على Windows، قارن المجلد الذي يفتحه مع المسار المحزوم أعلاه قبل أن تثق به.

هذه كل المواقع في مكان واحد:

شكل ملف JSON

كيف يعمل كائن mcpServers

الملف كله كائن JSON واحد. يبحث Claude Desktop عن خاصية على المستوى الأعلى اسمها mcpServers. وداخلها كل خاصية تمثل خادمًا واحدًا، واسم الخاصية هو التسمية التي تراها في التطبيق. وكل مدخل وصفة صغيرة لتشغيل برنامج على حاسوبك، ويتواصل Claude مع هذا البرنامج عبر الإدخال والإخراج القياسيين.

يعتمد command الصحيح على طريقة كتابة الخادم. فخوادم Node.js المنشورة على npm تبدأ بـ npx. أما الخوادم التي بنيتها أو نسختها بنفسك فتبدأ بـ node متبوعًا بمسار الملف المترجم. وتُشغَّل خوادم Python عادةً عبر uvx، ويحتاج ذلك إلى تثبيت أداة uv. والقاعدة واحدة في كل الحالات: أي شيء تكتبه كـ command يجب أن يعمل عند كتابته في Terminal، لأن هذا بالضبط ما يفعله Claude Desktop نيابةً عنك.

إذا أضاف Claude Desktop مدخلات أخرى على المستوى الأعلى في الملف (قد تخزن الإصدارات الأحدث بعض التفضيلات هناك)، فاتركها كما هي وأضف mcpServers بجانبها. فاستبدال الملف كله بمقتطف ملصوق هو السبب الذي يجعل الناس يفقدون تلك الإعدادات.

أمثلة لـ macOS وWindows

هذا خادم نظام الملفات الرسمي على Mac. استبدل username باسم حسابك الفعلي:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/Users/username/Desktop",
        "/Users/username/Downloads"
      ]
    }
  }
}

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

نسخة Windows مطابقة تمامًا باستثناء المسارات، ويجب مضاعفة كل شرطة مائلة عكسية لأن الشرطة الواحدة حرف هروب في JSON:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "C:\\Users\\username\\Desktop",
        "C:\\Users\\username\\Downloads"
      ]
    }
  }
}

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

ثلاثة تفاصيل تقوم بمعظم العمل هنا. يسمح العلم -y لأداة npx بتثبيت حزمة الخادم دون طرح سؤال لن يجيب عنه أحد. والمجلدات التي تأتي بعد اسم الحزمة هي المواضع الوحيدة التي يُسمح للخادم بالوصول إليها. وكل هذه المسارات مطلقة، لأن المسارات النسبية سبب كلاسيكي لعدم بدء الخادم أبدًا.

تحتاج أيضًا إلى Node.js، لأن npx يأتي معه. شغّل node --version في Terminal؛ إذا طبع رقم إصدار فأنت جاهز، والإصدار LTS هو الخيار الآمن.

💡 نصيحة: اختر التسمية في mcpServers لتكون مفهومة للبشر لا للآلة. filesystem أو notes أو weather كلها مناسبة، والاسم يظهر فقط في القوائم واسم ملف السجل.

أضف الخوادم والأسرار بأمان

متغيرات البيئة للأسرار

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

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/Users/username/Documents/notes"
      ]
    },
    "weather": {
      "command": "node",
      "args": ["/Users/username/tools/weather-server/build/index.js"],
      "env": {
        "WEATHER_API_TOKEN": "paste-your-token-here"
      }
    }
  }
}

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

لاحظ الفاصلة بين كتلتي الخادمين وغياب الفاصلة بعد الأخيرة. هذان الموضعان يسببان أعطالًا في الملفات أكثر من أي شيء آخر.

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

الخوادم البعيدة تستخدم الموصِّلات بدلًا من ذلك

يشغّل ملف JSON عمليات محلية. أما خادم MCP المستضاف عن بُعد فأمر مختلف: إنه يعمل في مكان آخر، وتصل إليه عبر عنوان URL. ويتوقع Claude Desktop إضافة هذه الخوادم من Settings، ثم Connectors، لا كمدخلات في claude_desktop_config.json. ولصق عنوان URL في command واحد من أهدأ الطرق للانتهاء بخادم لا يُحمَّل أبدًا.

أعد التشغيل وتأكد أنه يعمل

أغلق التطبيق بالكامل ثم أعد فتحه

يقرأ Claude Desktop الإعداد مرة واحدة، عند التشغيل. حفظ الملف لا يفعل شيئًا وحده. وإغلاق النافذة لا يكفي أيضًا، لأن التطبيق قد يستمر في العمل في الخلفية. على macOS اضغط Cmd+Q أو استخدم Claude، ثم Quit. وعلى Windows، أغلقه من أيقونة علبة النظام إذا بقي فيها. ثم افتحه من جديد.

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

تحقق من قائمة Connectors

بعد عودة التطبيق، انظر إلى مربع إدخال المحادثة وانقر زر Add files, connectors, and more. مرّر المؤشر فوق Connectors، وانقر Manage connectors، واختر خادمك من القائمة. يعرض الخادم الذي يعمل الأدوات التي يقدمها. فخادم نظام الملفات مثلًا يعرض أدوات لقراءة الملفات وكتابتها ونقلها والبحث فيها.

ثم شغّل اختبارًا حقيقيًا بأمر مثل "List the files in my Downloads folder." يطلب Claude الإذن قبل أن يستدعي أي أداة. وافق على الاستدعاء، ويجب أن تعود الإجابة بأسماء ملفات فعلية. أما إذا ردّ بأنه لا يملك صلاحية الوصول إلى ملفاتك، فهذا يعني أن الخادم لم يتصل.

أصلح الأخطاء التي تمنع التحميل

أخطاء صياغة JSON

حرف واحد في غير موضعه يوقف تحميل الملف كله. وهذه هي المشتبه بهم المعتادون:

• فاصلة زائدة بعد آخر خاصية أو آخر عنصر في مصفوفة.
• تعليق. لا يملك JSON تعليقات، لذا فالأسطر التي تحتوي // أخطاء.
• علامات تنصيص منحنية منسوخة من صفحة ويب أو معالج نصوص بدلًا من علامات التنصيص المستقيمة العادية.
• شرطة مائلة عكسية واحدة في مسار Windows.
• قوس ناقص بعد أن حذفت كتلة خادم.

يجمع هذا المقتطف ثلاثة منها في بضعة أسطر. هل تستطيع اكتشافها؟

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "C:\Users\username\Desktop",],
    }
  }
}

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

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

قبل إعادة التشغيل، تحقق من صحة الملف. يصلح أي مدقق JSON، أو يمكنك استخدام Node.js الذي لديك بالفعل:

node -e "JSON.parse(require('fs').readFileSync(process.argv[1],'utf8')); console.log('valid')" claude_desktop_config.json

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

إذا طبع valid، فالصياغة سليمة والمشكلة في مكان آخر.

مشكلات "الأمر غير موجود"

عندما يكون JSON صالحًا لكن الخادم ما زال يفشل، يكون الجاني عادةً command. فالتطبيق المكتبي لا يقرأ ملف إعدادات الـ shell لديك، لذلك قد يكون Node.js المثبت عبر مدير إصدارات غير مرئي له. شغّل which npx في Terminal، ضع المسار الكامل في حقل command بدلًا من npx.

أولًا، شغّل الأمر الدقيق يدويًا لترى إن كان يعمل خارج التطبيق:

npx -y @modelcontextprotocol/server-filesystem /Users/username/Desktop

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

على Windows، إذا أشار السجل إلى خطأ متعلق بـ ${APPDATA} داخل مسار، فأضف القيمة الموسّعة لـ %APPDATA% إلى كتلة env الخاصة بذلك الخادم، مثل "APPDATA": "C:\\Users\\username\\AppData\\Roaming\\". وتحقق أيضًا من وجود %APPDATA%\npm. فإن لم يكن موجودًا، فثبّت npm عامًا بالأمر npm install -g npm، ثم أعد تشغيل التطبيق.

اقرأ سجلات MCP

تخبرك السجلات بما رآه التطبيق. افتح مجلد السجلات من الجدول أعلاه وابحث عن نوعين من الملفات. يحتوي mcp.log على رسائل عامة عن الاتصالات والإخفاقات. أما الملفات التي تحمل اسم mcp-server-NAME.log فتحتوي على مخرجات stderr لكل خادم، وغالبًا ما تكون فيها رسالة الخطأ الحقيقية. وعلى Mac يمكنك متابعتها مباشرة:

tail -n 20 -f ~/Library/Logs/Claude/mcp*.log

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

وعلى Windows يؤدي PowerShell الغرض نفسه:

Get-Content "$env:APPDATA\Claude\logs\mcp.log" -Tail 40 -Wait

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

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

كيفية استخدام Sonnet 5 على PicassoIA

عين ثانية هي أسرع طريقة لاكتشاف فاصلة زائدة في غير مكانها. Claude Sonnet 5 على PicassoIA نموذج نصي يقرأ JSON الملصوق وتتبعات المكدس وحتى لقطات شاشة للأخطاء، لذلك يصلح جيدًا كمُراجِع للإعدادات.

افتح صفحة النموذج

انتقل إلى صفحة Claude Sonnet 5 في مجموعة Large Language Models، وافتح مربع الأمر النصي. احتفظ بتبويب متصفح واحد للنموذج وآخر لمحررك، حتى تتمكن من اللصق ذهابًا وإيابًا.

اضبط effort وطول المخرجات

يوفر النموذج عددًا من الإعدادات، وبعضها مهم هنا:

• effort: القيمة الافتراضية low، وهي توقف التفكير للحصول على أسرع إجابة. وهذا كافٍ لفحص الصياغة. انتقل إلى medium أو high عندما تحتاج إلى أن يستدل النموذج على المسارات عبر عدة خوادم.
• max_tokens: القيمة الافتراضية 8,192 كافية تمامًا لملف مصحح كامل.
• system_prompt: اضبطه مرة واحدة، على سبيل المثال: «أنت تراجع ملفات claude_desktop_config.json. حدد السطر الخاطئ بدقة، ثم أعد الملف بعد تصحيحه.»
• image: أرفق لقطة شاشة للخطأ. ارفع max_image_resolution فوق قيمته الافتراضية البالغة 0.5 ميغابكسل إذا كان نص السجل صغيرًا.

للتحقق السريع بنعم أو لا، يجيب Claude 4.5 Haiku أسرع. أما للغز متعدد الملفات العنيد، فإن Claude Opus 4.7 هو الخيار الأثقل.

الصق الإعداد واطرح سؤالك

استبدل كل توكن بعنصر نائب أولًا. ثم الصق الملف واطرح سؤالًا محددًا:

This claude_desktop_config.json is on Windows. The filesystem server never
appears in Claude Desktop. Check the JSON syntax, check the path escaping,
and tell me which line to fix first.

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

قارن الرد بملفك سطرًا بسطر بدلًا من لصقه دون تفكير، ثم شغّل أداة التحقق من Node.js التي رأيتها سابقًا على النتيجة.

ربط أدوات الصور والفيديو

بمجرد أن تعمل التوصيلات، يبدأ الجزء المثير: منح Claude أدوات تنفذ الأشياء. يوفر PicassoIA واجهة API للمطورين واتصال MCP، وكلاهما مقتصر على أربعة نماذج وقت كتابة هذا:

تُنشأ اتصالات MCP التي يوفرها PicassoIA من صفحة حسابك على picassoia.com بعد تسجيل الدخول. وهي مستضافة، لذا ينطبق مسار الموصلات الذي رأيته سابقًا: أضفها من الإعدادات ثم الموصلات، لا كإدخال mcpServers. تعمل المهام بشكل غير متزامن. يبدأ الطلب تنبؤًا، وتُجلب النتيجة بعد اكتماله. يمكن لكل حساب تشغيل 5 تنبؤات في الوقت نفسه، وهذا الحد مشترك بين كل اتصالات MCP التي تنشئها، لذا قد يدخل طلب الدفعة من Claude في طابور الانتظار خلف نفسه.

💡 نصيحة: اطلب صورة واحدة أولًا، وتحقق من النتيجة، ثم توسّع. أمر نصي واحد لصورة بنسبة 16:9 يكشف أسرع من دفعة من عشر صور إن كان الاتصال والأذونات سليمة.

الطلب الأول الجيد يكون محددًا: «أنشئ صورة بنسبة 16:9 لكوب خزفي على مكتب من خشب البلوط في ضوء صباحي ناعم، باستخدام PicassoIA Image.» يختار Claude الأداة، وينتظر انتهاء المهمة، ثم يسلمك الرابط. وإذا طلب الإذن في كل مرة، فهذه هي خطوة الموافقة نفسها التي رأيتها مع خادم نظام الملفات، وهي تعمل كما هو مقصود.

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

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

النصف الممتع هو الإبداع. افتح PicassoIA Image واكتب أمرًا واحدًا عن شيء يهمك، شارعًا تعرفه أو منتجًا تبيعه. ثم أعد صياغته باستخدام PicassoIA Image Editor Pro، وحرّك أفضل نتيجة بواسطة PicassoIA Video. تصفّح كل النماذج على picassoia.com/en/all-models، واختر نموذجًا لم تجربه، وأنشئ صورتك الأولى اليوم.