Claude Desktop MCP لا يعمل؟ حلول إعدادات الملف وخوادم HTTP

عمل خادم MCP الخاص بك بالأمس. واليوم يعرض Claude Desktop عدم وجود أدوات، أو رسالة "Server disconnected"، أو لا يعرض شيئًا على الإطلاق، والدليل الوحيد رسالة خطأ غامضة لا تقودك إلى أي مكان. يحدث هذا لمعظم من يربطون خادمًا محليًا، وغالبًا ما يكون السبب واحدًا من خمسة أشياء: ملف claude_desktop_config.json مكسور، أو أمر لا يجده التطبيق، أو خادم يطبع نصًا خاطئًا على stdout، أو خادم HTTP أُضيف بطريقة خاطئة، أو تطبيق لم يُعد تشغيله بالكامل قط.

يستعرض هذا المقال كل خلل بالترتيب الذي يجب أن تفحصه به، مع JSON والمسارات والأوامر الدقيقة لنسخها ولصقها. ابدأ من الأعلى وتوقّف عند اللحظة التي تظهر فيها أدواتك. معظم الحلول تستغرق أقل من خمس دقائق.

💡 الإجابة السريعة: أغلق Claude Desktop من الصينية أو شريط القوائم (وليس مجرد النافذة)، ومرّر الإعدادات عبر مدقق JSON، واستبدل npx بمساره المطلق، وأضف الخوادم البعيدة من Settings, Connectors بدلًا من ملف الإعدادات. هذا وحده يصلح معظم الحالات.

تحقق من الأساسيات أولًا

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

أغلق Claude Desktop بالكامل

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

انقر بزر الفأرة الأيمن على أيقونة الصينية (أو استخدم شريط القوائم)، واختر Quit، وانتظر ثانيتين، ثم افتح التطبيق من جديد. افعل ذلك بعد كل تغيير، حتى لو كان حرفًا واحدًا.

افتح ملف الإعدادات الصحيح

لا تبحث عن الملف يدويًا. افتح Settings، واختر Developer، ثم اضغط Edit Config. سيفتح هذا الملف الدقيق الذي يقرؤه التطبيق. تبدو المواقع المعتادة كما يلي:

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

إليك إعدادًا أدنى يعمل. إذا حُمّل هذا الإعداد ولم يُحمَّل إعدادك، فالفرق بين الملفين هو مكمن الخلل.

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/you/Documents"]
    }
  }
}

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

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

يكتب كل خادم محلي سجلًّا خاصًا به، اسمه mcp-server-NAME.log، بجانب سجل عام mcp.log. وفي Settings, Developer يُظهر كل خادم أيضًا ما إذا كان يعمل أم فشل، فتعرف الإدخال المشكلة بنظرة واحدة.

لمتابعة السجلات مباشرة على macOS:

tail -n 40 -F ~/Library/Logs/Claude/mcp*.log

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

وفي PowerShell على Windows:

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

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

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

أصلح JSON في ملف الإعدادات

Claude Desktop لا يتسامح مع الأخطاء النحوية. ففاصلة واحدة زائدة تجعل كل الخوادم في الملف تختفي، وليس الخادم الذي عدّلته للتو فقط.

أخطاء الصياغة التي تكسر كل شيء

تحقّق من هذه القائمة سطرًا سطرًا:

• الفواصل الزائدة بعد آخر خاصية في كائن أو مصفوفة.
• التعليقات. لا تحتوي JSON على تعليقات، لذلك فإن أسطر // التي نسختها من درس تعليمي ستكسر الملف.
• علامات التنصيص الذكية. تحوّل تطبيقات المحادثة ومعالجات النصوص " إلى علامات منحنية تبدو متطابقة وتفشل فورًا.
• فاصلة مفقودة بين إدخالي خادمين.
• اسم المستوى الأعلى الخاطئ. يجب أن يكون mcpServers بالضبط، مع حرف S الكبير. الأشكال مثل mcpservers أو servers يتم تجاهلها بصمت.
• أرقام في env. يجب أن تكون قيم البيئة نصوصًا، لذا اكتب "PORT": "8080"، لا "PORT": 8080.
• أقسام محذوفة. إذا كان الملف يحتوي على إعدادات أخرى في المستوى الأعلى، فاحتفظ بها عند لصق كتلة mcpServers جديدة.

إليك ملف معطوب نموذجي:

{
  "mcpServers": {
    "notes": {
      "command": "node",
      // path to my server
      "args": ["C:\Users\Ana\notes-server\index.js"],
    }
  }
}

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

وهذه هي النسخة المصححة:

{
  "mcpServers": {
    "notes": {
      "command": "node",
      "args": ["C:\\Users\\Ana\\notes-server\\index.js"]
    }
  }
}

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

أسرع طريقة لاكتشاف كل ذلك دفعة واحدة هي ترك محلّل الصياغة يقوم بالعمل. يأتي Python مع واحد منها:

python -m json.tool claude_desktop_config.json

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

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

مسارات Windows والشرطات المائلة العكسية

الشرطة المائلة العكسية هي محرف الهروب في JSON، لذلك فإن C:\Users\Ana غير صالح لأن \U ليس محرف هروب حقيقيًا. لديك خياران آمنان:

1. ضاعف كل شرطة مائلة عكسية: C:\\Users\\Ana\\notes-server\\index.js
2. استخدم الشرطات المائلة الأمامية: C:/Users/Ana/notes-server/index.js

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

أصلح أخطاء الأمر وبدء التشغيل

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

لماذا يحدث spawn npx ENOENT

تعني ENOENT "لا يوجد ملف أو مجلد بهذا الاسم". فعند تشغيل Claude Desktop من Dock أو قائمة ابدأ، لا يقرأ ملف إعدادات الصدفة الخاص بك، ولذلك لا يرى PATH الموجود لديك في الطرفية. وإذا ثبّتّ Node عبر nvm أو fnm أو asdf أو Volta، فإن الملفات التنفيذية تعيش في مجلد لا تعرفه إلا صدفتك. يعمل الأمر في الطرفية ويفشل داخل التطبيق، ولهذا يبدو الأمر مربكًا جدًا.

استخدم المسارات المطلقة لـ Node

اسأل الطرفية أين يوجد الملف التنفيذي فعلًا:

which npx     # macOS
where npx     # Windows

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

ثم ألصق المسار الكامل في command. ولأن npx نفسه يحتاج إلى إيجاد node، أضف إدخال PATH في env يتضمن المجلد نفسه:

{
  "mcpServers": {
    "filesystem": {
      "command": "/Users/you/.nvm/versions/node/v22.11.0/bin/npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/you/Documents"],
      "env": {
        "PATH": "/Users/you/.nvm/versions/node/v22.11.0/bin:/usr/local/bin:/usr/bin:/bin"
      }
    }
  }
}

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

شغّل node --version أيضًا. فكثير من الخوادم التي تُشغَّل عبر npx تحتاج إلى إصدار LTS حديث من Node، والنسخة القديمة المثبتة في النظام سبب شائع وخفي.

غلاف cmd في Windows

في Windows، npx هو في الحقيقة ملف دفعي اسمه npx.cmd، وتشغيله مباشرة قد يفشل. غلّفه بـ cmd /c حتى تحلّه الصدفة بشكل صحيح:

{
  "mcpServers": {
    "filesystem": {
      "command": "cmd",
      "args": ["/c", "npx", "-y", "@modelcontextprotocol/server-filesystem", "C:/Users/Ana/Documents"]
    }
  }
}

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

أبقِ stdout نظيفًا

يصيب هذا الخلل من يكتبون خادمهم الخاص. فالخادم من نوع stdio يتحدث مع Claude عبر رسائل JSON-RPC على stdout، ولا يُسمح بأي شيء آخر هناك. فسطر console.log("server started") واحد عابر يفسد التدفق، ويقطع التطبيق الاتصال مع خطأ Unexpected token.

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

أصلح خوادم HTTP والخوادم البعيدة

تسبب خوادم HTTP أكبر قدر من الالتباس، لأن ملف الإعدادات يبدو المكان المناسب لإضافتها. لكنه ليس كذلك.

ملف الإعدادات يشغّل الخوادم المحلية فقط

تشغّل الإدخالات الموجودة تحت mcpServers برنامجًا على جهازك وتتواصل معه عبر stdin وstdout. ولا تتصل بعنوان ويب. إضافة "url": "https://example.com/mcp" داخل هذه الكتلة هي أكثر أخطاء HTTP شيوعًا، لأن التطبيق لا يملك طريقة لاستخدام هذا الإدخال.

أضف موصلًا مخصصًا

تمر الخوادم البعيدة عبر Connectors. الموصلات المخصصة متاحة في خطط Pro وMax وTeam وEnterprise، وفي خطتي Team أو Enterprise قد يحتاج مالك المؤسسة إلى إضافة الموصل أولًا.

1. افتح Settings واختر Connectors.
2. اضغط Add custom connector.
3. ألصق عنوان HTTPS لنقطة نهاية الخادم، وغالبًا ما ينتهي بـ /mcp.
4. سجّل الدخول إذا طلب الخادم OAuth.
5. فعّل الموصل من قائمة الأدوات في محادثة جديدة.

اختر نقطة نهاية من نوع Streamable HTTP. فالخادم الذي يتحدث فقط بنقل SSE القديم يسبب عدم توافق شائعًا. وعندما يفشل الموصل، يساعدك هذا الجدول على تضييق السبب:

الخادم المرتبط بالعنوان localhost هو المتهم المعتاد عندما يرفض موصل مخصص الاتصال، لأن العنوان يعني شيئًا مختلفًا عن المكان الذي يصدر منه الطلب.

الربط عبر mcp-remote

عندما يكون الخادم خاصًا أو محليًا أو يحتاج إلى ترويسة، تعمل حزمة mcp-remote كجسر stdio. يشغّلها Claude مثل أي خادم محلي آخر، وتعيد توجيه الحركة إلى نقطة نهاية HTTP الخاصة بك:

{
  "mcpServers": {
    "my-remote": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://example.com/mcp",
        "--header",
        "Authorization:${AUTH_HEADER}"
      ],
      "env": {
        "AUTH_HEADER": "Bearer YOUR_TOKEN"
      }
    }
  }
}

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

تفصيلان مهمان هنا. أولًا، اكتب الترويسة بدون مسافة بعد النقطتين واحفظ القيمة الحقيقية في env. وفي Windows، قد تتشوه المسافات داخل args عند بدء npx، وهذا التخطيط يتجنب الخلل. ثانيًا، يحتوي mcp-remote على خيارات لفرض سلوك HTTP فقط أو SSE فقط، لذا راجع ملف README الخاص به عندما يختار التفاوض الافتراضي النقل الخاطئ. تنطبق كل الأقسام السابقة هنا: أعد التشغيل بالكامل، واستخدم المسارات المطلقة، واقرأ السجل.

اختبر الخوادم خارج Claude

عندما لا تستطيع تحديد ما إذا كان الخطأ في الخادم أم في التطبيق، أخرج التطبيق من المعادلة.

شغّل MCP Inspector

يتصل MCP Inspector الرسمي بالخادم ويعرض أدواته في تبويب متصفح:

npx @modelcontextprotocol/inspector node build/index.js

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

بالنسبة إلى خادم HTTP، افتح Inspector واختر نوع النقل المطابق، ثم ألصق الرابط. تفصل النتيجة المشكلة بوضوح:

• تظهر الأدوات في Inspector لكن ليس في Claude: المشكلة في الإعدادات أو PATH أو إعادة التشغيل.
• يفشل Inspector أيضًا: الخادم هو المشكلة، فأصلحه هناك أولًا.

افحص HTTP باستخدام curl

بالنسبة إلى خادم Streamable HTTP، أرسل طلب initialize حقيقيًا واقرأ رمز الحالة:

curl -i -X POST https://example.com/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"curl-test","version":"0.0.1"}}}'

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

استخدم أدوات PicassoIA داخل Claude

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

مهام التوليد غير متزامنة. تعيد الأداة معرّف التنبؤ فورًا، ثم يتحقق Claude من الحالة حتى تنجح المهمة أو تفشل. هذا التصميم يفسر معظم تقارير "التعليق":

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

استخدم Claude Sonnet 5 على PicassoIA

عالق مع إعداد يبدو صحيحًا ومع ذلك يفشل؟ فاطلب رأيًا ثانيًا. يعمل Claude Sonnet 5 على PicassoIA وهو مصمم لتصحيح الشيفرة، ويمكنه قراءة لقطات شاشة لأشرطة الأخطاء.

1. افتح صفحة النموذج. انتقل إلى Claude Sonnet 5 على PicassoIA.
2. املأ الأمر النصي. ألصق الإعداد، وآخر 30 سطرًا من السجل، ونظام التشغيل، وإصدار Node لديك، وما كنت تتوقع حدوثه. أزل كل الرموز أولًا.
3. أرفق لقطة شاشة. يقبل حقل image صورة للخطأ. ارفع max_image_resolution فوق قيمته الافتراضية البالغة 0.5 ميغابكسل إذا بدا النص غير واضح بعد التصغير.
4. اضبط الجهد. الافتراضي low هو الأسرع. انتقل إلى high عندما تتفاعل عدة خوادم معًا أو يكون السبب غير واضح.
5. أضف نظام التوجيه. شيء مثل: "أنت مساعد لاستكشاف أخطاء MCP وإصلاحها. أعد JSON المصحح أولًا، ثم قائمة قصيرة بالأسباب."
6. ولّد وقارن. قارن الإجابة بملفك، وطبّق تغييرًا واحدًا في كل مرة، وأعد تشغيل التطبيق بالكامل بعد كل تغيير.

💡 لا تلصق أبدًا رموزًا حية في أي نافذة محادثة. استبدلها بـ YOUR_TOKEN وأعد القيمة الحقيقية إلى ملفك المحلي فقط.

بالنسبة إلى المشكلات العنيدة متعددة الملفات، تتوفر أيضًا Claude Fable 5 وClaude Opus 4.7 في الفئة نفسها.

أنشئ أول صورة لك اليوم

خوادمك تعمل، والأدوات مرئية، والجزء الصعب خلفك. الآن امضِ عشر دقائق في الجزء الممتع. افتح PicassoIA Image واكتب أمرًا نصيًا لمشهد تود فعلًا تعليقه على حائط. حسّنه باستخدام PicassoIA Image Editor Pro، ثم حوّله إلى فيديو باستخدام PicassoIA Video.

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