أين يحفظ Claude Code إعدادات MCP؟ المواقع والإعدادات موضّحة

تشغّل claude mcp add، ويتصل الخادم، وبعد أسبوع يسألك زميلك أين ذهب ذلك الإعداد فعلًا. لا يحتفظ Claude Code بإعدادات MCP في ملف واحد منظم. بل يوزعها على ~/.claude.json، و.mcp.json على مستوى المشروع، وعدة ملفات settings.json، وفي إعدادات الشركات، ملف سياسة مُدارة. إذا عدّلت الملف الخطأ فلن يتغير شيء. وإذا عدّلت الملف الصحيح دون أن تعرف ترتيب الأولوية، فسيتغلب تعريف مختلف بهدوء.

يرسم هذا المقال كل موقع على macOS وWindows وLinux، ويوضح أي تعريف يتغلب عندما يذكر ملفان الخادم نفسه، ويسرد الأوامر ومتغيرات البيئة وإعدادات المهلة المهمة في الاستخدام اليومي. تم التحقق من كل مسار وخيار وارد أدناه مقابل وثائق Claude Code الحالية، لذا يمكنك نسخها كما هي.

أين تُحفظ الملفات فعلًا

يملك Claude Code ثلاثة نطاقات للخوادم التي تضيفها بنفسك، إضافة إلى طبقة مؤسسية تعلوها. يحدد النطاق أمرين: المشاريع التي تحمّل الخادم، وهل يُنقل التعريف مع المستودع.

ثلاثة نطاقات، ثلاثة مواقع

النطاق المحلي هو الافتراضي. الخادم الذي يُضاف دون --scope يُحمَّل فقط في المشروع الذي شغّلت فيه الأمر، ويبقى خاصًا بك. يكتبه Claude Code في ~/.claude.json تحت مسار ذلك المشروع:

{
  "projects": {
    "/path/to/your/project": {
      "mcpServers": {
        "stripe": {
          "type": "http",
          "url": "https://mcp.stripe.com"
        }
      }
    }
  }
}

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

نطاق المشروع يكتب ملف .mcp.json في جذر المستودع. وهو مصمم ليُرفع إلى المستودع، فيحصل الجميع في الفريق على الأدوات نفسها. أما نطاق المستخدم فيحتفظ بالتعريف في الملف نفسه ~/.claude.json، خارج أي مسار مشروع، فيراه كل مشروع تفتحه.

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

المسارات على Windows وmacOS وLinux

على Windows، يعني ~ المسار %USERPROFILE%، لذا فملف المستوى الشخصي هو %USERPROFILE%\.claude.json. ملف .mcp.json نسبي إلى جذر مشروعك على كل الأنظمة. الملف المُدار وحده يتغير حسب نظام التشغيل، لأنه يقع في مجلد على مستوى النظام يتحكم فيه المسؤول.

إذا أردت وضع ملفات المجلد الرئيسي في مكان آخر، فاضبط CLAUDE_CONFIG_DIR. عندها يخزّن Claude Code إعداداتك وسجل الجلسات والإضافات هناك بدلًا من ~/.claude.

فخ تسمية النطاق المحلي

كلمة "محلي" تعني أمرين مختلفين في Claude Code. نطاق MCP المحلي يقع في ~/.claude.json داخل مجلدك الرئيسي. أما الإعدادات المحلية العامة فتقع في .claude/settings.local.json داخل المشروع. البحث عن خادم MCP أضفته بالنطاق الافتراضي داخل settings.local.json لن يجد شيئًا، وهذا الخلط وحده يفسر جزءًا كبيرًا من أسئلة "أين اختفى خادمي؟".

💡 تُوضع تعريفات الخوادم في .mcp.json أو ~/.claude.json، وأوامر claude mcp تكتبها عنك. أما ملفات settings.json فتحتفظ بالموافقات وقوائم السماح والمنع، وسنأتي إليها لاحقًا.

داخل ملف .mcp.json

عندما تضيف خادمًا بالأمر --scope project، ينشئ Claude Code هذا الملف أو يحدّثه تلقائيًا. يمكنك أيضًا كتابته يدويًا ورفعه إلى المستودع. يحتوي على حقل غلاف واحد هو mcpServers، وإدخال واحد لكل خادم.

مثال عملي

{
  "mcpServers": {
    "docs-search": {
      "type": "http",
      "url": "https://example.com/mcp",
      "headers": {
        "Authorization": "Bearer ${SERVICE_TOKEN}"
      }
    },
    "local-files": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@example/files-server"],
      "env": {
        "ROOT_DIR": "${PROJECT_ROOT:-.}"
      },
      "timeout": 600000
    }
  }
}

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

يقبل حقل type القيم http وsse وstdio وws. الاسم streamable-http يعمل كاسم بديل للقيمة http، ما يعني أن المقتطف المنسوخ من وثائق الخادم نفسها يُحمَّل غالبًا دون تعديل. يحتاج إدخال stdio إلى command، واختياريًا args وenv. ويحتاج الإدخال البعيد إلى url، واختياريًا headers.

هناك تفصيل يربك الناس عندما ينسخون إعدادات من عميل آخر مثل Claude Desktop. الغلاف mcpServers نفسه يعمل داخل .mcp.json، لكن claude mcp add-json يتوقع الكائن الموجود داخل الغلاف فقط، لا الغلاف نفسه.

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

لأن .mcp.json يُرفع إلى المستودع، فلا مكان للتوكنات فيه أبدًا. يوسّع Claude Code شكلين من مراجع المتغيرات:

• ${VAR} يتوسع إلى قيمة VAR.
• ${VAR:-default} يتوسع إلى VAR إذا كان مضبوطًا، وإلى default في الحالة الأخرى.

يعمل التوسيع في قيم command وargs وenv وurl وheaders. إذا كان المتغير غير مضبوط ولا يملك قيمة افتراضية، فإن الملف يُحمَّل مع ذلك. يطبع Claude Code تحذير متغير مفقود للخادم في claude mcp list، ويستخدم نص ${VAR} الخام كما هو، ولهذا قد يفشل الخادم بسبب نص حرفي غريب يظهر في ترويسته.

وهناك أيضًا قاعدة أمان. في url وheaders لخادم بعيد، تُقرأ المتغيرات الحاملة للاعتماد مثل ANTHROPIC_AUTH_TOKEN وNPM_TOKEN على أنها فارغة. وهذا يمنع مستودعًا مستنسخًا من إرسال بيانات اعتمادك في Claude Code أو السحابة إلى خادم يذكره.

💡 صدّر التوكن الحقيقي في ملف إعدادات الصدفة أو في مدير الأسرار، وارفع المرجع ${SERVICE_TOKEN} فقط.

إضافة الخوادم من الطرفية

نادرًا ما تحتاج إلى لمس JSON بنفسك. مجموعة الأوامر claude mcp add تكتب في الملف الصحيح للنطاق الذي تختاره، وهي أكثر طريقة أمانًا لتجنب خطأ مطبعي يكسر ~/.claude.json.

أوامر HTTP وstdio

# Remote HTTP server with a bearer token
claude mcp add --transport http docs-search https://example.com/mcp \
  --header "Authorization: Bearer your-token"

# Local stdio server. The -- separates Claude's options from the server command
claude mcp add --transport stdio --env SERVICE_TOKEN=abc123 local-files -- npx -y @example/files-server

# Shared with the team and written to .mcp.json
claude mcp add --scope project --transport http docs-search https://example.com/mcp

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

بالنسبة لخوادم stdio، الشرطتان المزدوجتان ليستا اختياريتين. كل ما قبلهما يخص Claude Code، وكل ما بعدهما هو الأمر الذي يشغّل الخادم.

الخوادم البعيدة تستخدم http أو sse، بينما تستخدم العملية المحلية stdio. خوادم WebSocket ليس لها خيار مخصص، لذا تضيفها عبر JSON:

claude mcp add-json events-server '{"type":"ws","url":"wss://example.com/events"}'

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

الخوادم التي تستخدم OAuth تقبل --client-id و--client-secret و--callback-port، وclaude mcp login <name> يسجّل الدخول من سطر الأوامر.

التحقق مما اتصل

ثلاثة أوامر تجيب عن معظم الأسئلة: claude mcp list يعرض كل الخوادم، وclaude mcp get <name> يعرض خادمًا واحدًا، وclaude mcp remove <name> يحذف خادمًا. داخل الجلسة، يفتح /mcp العرض نفسه ويتيح لك المصادقة.

أي تعريف يتغلب

عندما يظهر الخادم نفسه في أكثر من مكان، يتصل Claude Code به مرة واحدة ويستخدم المصدر الأعلى أولوية.

الأولوية، من الأعلى

1. خادم من الإعداد المُدار managedMcpServers (Claude Code v2.1.259 أو أحدث)
2. النطاق المحلي
3. نطاق المشروع
4. نطاق المستخدم
5. الخوادم التي توفرها الإضافات
6. موصلات claude.ai

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

التفصيل الأهم: يُستخدم الإدخال كاملًا من المصدر الفائز، ولا تُدمج الحقول. لنفترض أن docs-search موجود في نطاق المستخدم مع ترويسة Authorization، وموجود مرة أخرى في نطاق المشروع بدون ترويسة. يتغلب تعريف المشروع كليًا، ولا تظهر الترويسة من إدخال المستخدم أبدًا.

طلبات الموافقة للخوادم المشتركة

لأسباب أمنية، يطلب Claude Code الموافقة في الجلسات التفاعلية قبل أن يستخدم خادمًا بنطاق المشروع من .mcp.json. ثلاثة إعدادات تتحكم في النتيجة:

{
  "enabledMcpjsonServers": ["docs-search"],
  "disabledMcpjsonServers": ["local-files"]
}

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

اتخذت قرارًا تندم عليه؟ claude mcp reset-project-choices يمسح الموافقات.

منذ الإصدار v2.1.196، لا يستطيع المستودع المستنسخ الموافقة على خوادمه بنفسه. الموافقات المُلتزَم بها في .claude/settings.json الخاص بالمشروع تُتجاهل في مجلد لم تثق به، ويبقى الخادم عند ⏸ Pending approval. أما الموافقات من ملف إعدادات المستخدم ~/.claude/settings.json، ومن الإعدادات المُدارة، ومن --settings، فتظل سارية. وملف .claude/settings.local.json غير المتتبع يعمل أيضًا، بعد أن تثق بالمجلد.

عمليات التشغيل غير التفاعلية مثل claude -p تحمّل خوادم المشروع دون طلب تأكيد، إلا إذا بدأتها باستخدام --strict-mcp-config. هذا الخيار يخبر Claude Code بأن يستخدم فقط الخوادم الممررة عبر --mcp-config.

💡 راجع .mcp.json في طلب السحب كما تراجع سكربتًا. إدخال stdio يشغّل أمرًا على جهاز كل عضو في الفريق.

ملفات الإعدادات وضوابط السياسة

ملفات الإعدادات، من الأعلى أولوية

الإعداد على مستوى أعلى يتجاوز الإعداد نفسه على مستوى أدنى. ~/.claude.json ملف منفصل يكتبه Claude Code لنفسه. يحتفظ بجلسة تسجيل دخولك، وإعدادات خوادم MCP، والحالة الخاصة بكل مشروع مثل قرارات الثقة، والخيارات العامة التي يغيّرها /config. لا تحتاج إلى تعديله يدويًا.

قوائم السماح والخوادم المُدارة

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

• disabledMcpServers يسمح للمستخدم بإلغاء اشتراك خوادم محددة من المستخدم أو الإضافات أو المُدارة أو claude.ai.
• allowedMcpServers وdeniedMcpServers يصفّيان حسب اسم الخادم أو حسب نمط serverUrl.
• managedMcpServers إعداد مُدار يوفر خوادم للجميع إلى جانب الخوادم التي يضيفها المستخدمون.
• managed-mcp.json ينشر مجموعة ثابتة من الخوادم من المسارات الموجودة على النظام التي ذُكرت سابقًا.

نشر managed-mcp.json له أثر جانبي يستحق المعرفة. افتراضيًا، يحجب موصلات claude.ai التي يجلبها Claude Code بنفسه. لتحميلها إلى جانب خوادمك المُدارة، اضبط "allowAllClaudeAiMcps": true في مصدر إعدادات مُدارة. ضبط متغير البيئة ENABLE_CLAUDEAI_MCP_SERVERS=false يطفئ الموصلات على جهاز واحد فقط.

المهلات وحدود الإخراج

مهلات البدء والأدوات

يهم مؤقتان، وهما سهلا الخلط.

يتجاوز timeout الخاص بكل خادم المتغير MCP_TOOL_TIMEOUT لذلك الخادم وحده. القيم التي تقل عن 1000 تُهمل وتعود إلى MCP_TOOL_TIMEOUT. وعندما لا يكون ذلك المتغير مضبوطًا، تكون القيمة الافتراضية نحو 28 ساعة. إشعارات التقدم القادمة من الخادم لا تمدد الحد.

مخرجات الأدوات الكبيرة

يحذر Claude Code عندما تعيد أي أداة MCP أكثر من 10,000 توكن، ويحدّ المخرجات عند 25,000 توكن افتراضيًا. ارفع الحد باستخدام MAX_MCP_OUTPUT_TOKENS=50000 claude، أو اجعله دائمًا عبر الحقل env في ملف إعدادات:

{
  "env": {
    "MCP_TIMEOUT": "10000",
    "MAX_MCP_OUTPUT_TOKENS": "50000"
  }
}

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

إصلاح الإعدادات المعطوبة بسرعة

الأعراض والحلول

إذا فشل تحليل ~/.claude.json في أي وقت، ينسخ Claude Code الملف المعطوب إلى ~/.claude/backups/.claude.json.corrupted.<timestamp> ويسألك: هل تريد الخروج وإصلاحه يدويًا، أم إعادة الضبط إلى الإعدادات الافتراضية؟ لاستعادة حالتك السابقة، انسخ أحد أحدث خمسة ملفات .claude.json.backup.<timestamp> من ~/.claude/backups/ إلى مكانها.

💡 التعديلات اليدوية على ~/.claude.json نادرًا ما تستحق المخاطرة. فضّل claude mcp add وadd-json وremove، واحتفظ بنسخة من الملف قبل أي تعديل يدوي.

أنشئ صورك بنفسك باستخدام Picasso IA

ينتهي عمل الإعدادات لحظة يعرض فيها خادم ✔ Connected، لكن توثيقه يستغرق وقتًا أطول من تنفيذه. لقطات الشاشة في README، ومخططات التهيئة، والمقاطع القصيرة لجلسات الطرفية تبطئ الفريق. هنا يساعد Picasso IA، بنماذج للنص والصورة والفيديو في مكان واحد.

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

Claude Sonnet 5 نموذج لغوي مبني لمهام البرمجة واستخدام الأدوات، ما يجعله مفيدًا لصياغة إدخال إعدادات أو مراجعته قبل رفعه. تعرض صفحة النموذج هذه المدخلات:

1. افتح صفحة النموذج والصق طلبك في Prompt. على سبيل المثال: "حوّل أمر claude mcp add هذا إلى إدخال .mcp.json يقرأ ترويسة Authorization من متغير بيئة."
2. اضبط Effort. القيمة الافتراضية هي low، وهي تطفئ التفكير للحصول على أسرع رد وأرخصه. اختر high أو max عندما تمتد المشكلة عبر عدة ملفات.
3. أضف System Prompt مثل "أجب بتنسيق JSON صالح فقط، دون تعليق" وأعد استخدامه طوال الجلسة.
4. اترك Max Tokens كما هو إلا إذا كان الناتج طويلًا. القيمة الافتراضية 8,192.
5. أرفق صورة إذا كان لديك لقطة شاشة لخطأ. يقرأها النموذج كسياق.
6. شغّله، ثم تحقق. الصق النتيجة في .mcp.json وشغّل claude mcp get <name> لتتأكد من اتصال الخادم.

💡 تعامل مع الإعدادات المولّدة كمسودة. المسارات والخيارات والإعدادات تتغير بين الإصدارات، لذا تحقق من كل واحد منها مقابل الوثائق الرسمية.

أما الجانب البصري، فنماذج تحويل النص إلى صورة مثل PicassoIA Image وSeedream 5 Pro يمكنها إنتاج صورة ترويسة لصفحة توثيق أو لمنشور سجل التغييرات. لتعديل صورة لديك بالفعل، افتح PicassoIA Image Editor Pro. وللحركة، يحوّل PicassoIA Video وSeedance 2.5 Lite الأمر النصي أو الصورة الثابتة إلى مقطع قصير.

تقدم PicassoIA أيضًا اتصالات MCP لنماذج الصور والفيديو، وتديرها من حسابك على picassoia.com/en/mcp/accounts. وبعد أن تحصل على تفاصيل الاتصال، يُضاف خادم HTTP بالنمط نفسه claude mcp add --transport http الموضح أعلاه.

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