خوادم MCP في Gemini CLI: كيف تضيفها وتضبط إعداداتها

يفيدك Gemini CLI منذ اللحظة التي تثبّته فيها. ويصبح أكثر فائدة حين يتمكن من الوصول إلى متتبّع المشكلات، أو قاعدة البيانات، أو مجلد ملفات التصميم دون أن تلصق أي شيء في الأمر النصي. الجسر هنا هو Model Context Protocol، وكل جسر منها هو خادم MCP. يستطيع Gemini CLI التواصل مع الخوادم التي تعمل كعمليات محلية، والخوادم خلف نقطة نهاية HTTP عادية، وكذلك نقاط نهاية SSE للبث القديمة. ويوفر طريقتين لتسجيلها: أمر gemini mcp add واحد، أو بضعة أسطر في settings.json.

يشرح هذا المقال الطريقتين بأوامر حقيقية، ثم يتناول الأجزاء التي تتعطل عادةً: النطاقات، والأسرار، وتصفية الأدوات، وOAuth، وحالة Disconnected المزعجة. كل علامة وحقل وارد أدناه مأخوذ من الوثائق الرسمية لخوادم MCP في Gemini CLI، وحيثما يختلف السلوك بين الإصدارات أذكر ذلك.

💡 الإجابة السريعة: شغّل gemini mcp add -s user <name> <command-or-url>، ثم اكتب /mcp داخل CLI. يجب أن يظهر الخادم كمتصل وأن يعرض قائمة أدواته.

ماذا تضيف خوادم MCP إلى Gemini CLI

عند البدء، يقرأ Gemini CLI الخوادم المُعدّة لديك، ويتصل بكل واحد منها، ويسأله عما يقدّمه. يجيب الخادم بقائمة من الأدوات، ولكل أداة اسم ووصف ومخطط JSON لمدخلاتها. يرى النموذج هذه الأدوات إلى جانب الأدوات المدمجة (قراءة الملفات، وأوامر الشل، والبحث على الويب) ويستدعيها عندما يحتاجها الأمر النصي.

الأدوات والأوامر النصية الجاهزة والموارد

يمكن للخادم أن يعرض ثلاثة أنواع من الأشياء:

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

تأتي معظم الخوادم بأدوات فقط، وهنا يُجدي جهد الإعداد. كل ما يلي يدور حول توصيل هذه الأدوات بأمان.

اختيار وسيلة النقل

يستخدم كل إدخال للخادم وسيلة نقل واحدة من ثلاث. والحقل الذي تضبطه يحدد الوسيلة التي يستخدمها CLI.

مع stdio، يشغّل CLI العملية ويتواصل معها عبر الإدخال والإخراج القياسيين. وهذا يعني أن الخادم يجب ألا يطبع نصوصًا عشوائية إلى stdout أبدًا. تذهب السجلات إلى stderr، وإلا ينكسر تدفق البروتوكول ويخرج الخادم من الاتصال.

غالبًا ما يُحسم الاختيار نيابةً عنك. إن كان الخادم حزمة أو سكربت على جهازك، فاستخدم stdio. وإن كان موجودًا على عنوان URL وكان المزوّد يقدّم HTTP وSSE معًا، فاختر HTTP، لأن SSE وسيلة أقدم وموجودة أساسًا من أجل الخوادم التي لم تنتقل بعد.

أضف خادمًا بأمر واحد

إن لم يكن gemini موجودًا في PATH لديك بعد، فثبّته باستخدام npm install -g @google/gemini-cli. بعد ذلك يصبح أمر الإضافة أسرع طريق.

صيغة الأمر gemini mcp add

gemini mcp add [options] <name> <commandOrUrl> [args...]

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

يأتي الاسم أولًا، ثم الملف التنفيذي أو عنوان URL، ثم أي وسائط يحتاجها الخادم. أهم الخيارات التي ستستخدمها:

أمثلة محلية عبر stdio وبعيدة

سكربت محلي، يُحفظ لمستخدمك حتى يعمل في كل مجلد:

gemini mcp add -s user -e ISSUES_TOKEN='$ISSUES_TOKEN' issues node /home/me/mcp/issues-server.js

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

خادم مستضاف عبر streamable HTTP مع ترويسة bearer:

gemini mcp add --transport http --header "Authorization: Bearer abc123" docs-search https://mcp.example.com/mcp

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

نقطة نهاية SSE أقدم:

gemini mcp add --transport sse legacy-events http://localhost:8080/sse

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

تستخدم الإدارة اليومية عائلة الأوامر نفسها:

gemini mcp list
gemini mcp disable issues --session
gemini mcp enable issues
gemini mcp remove issues -s user

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

تغيّر العلامة --session على enable وdisable الحالةَ للجلسة الحالية فقط. ومن دونها يُحفظ الاختيار في ~/.gemini/mcp-server-enablement.json.

💡 انتبه إلى علامات الاقتباس. في المثال الأول تُبقي علامات الاقتباس المفردة $ISSUES_TOKEN عنصرًا نائبًا. ومع علامات الاقتباس المزدوجة يوسّع الشل القيمة أولًا، فيدخل الرمز الفعلي إلى settings.json. افتح الملف بعد إضافة أي خادم وتحقق.

💡 الوسائط التي تبدأ بشرطة، مثل npx -y، قد يخطئ محلل العلامات في اعتبارها خيارات CLI. بالنسبة إلى الخوادم التي تُشغَّل بهذه الطريقة، اكتب الإدخال في settings.json بدلًا من ذلك.

تحرير settings.json يدويًا

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

نطاق المستخدم أو نطاق المشروع

• نطاق المستخدم: ~/.gemini/settings.json. يتبعك إلى كل مجلد.
• نطاق المشروع: .gemini/settings.json داخل المستودع. ارفعه إلى المستودع فيحصل الفريق كله على الخوادم نفسها.

يُقرأ ملف المشروع بعد ملف المستخدم، لذا يكون له الغلبة إذا عرّف الملفان الخادم نفسه بالاسم نفسه. وتذكّر أن gemini mcp add يكتب في نطاق المشروع ما لم تمرر -s user.

ملف متعدد الخوادم يعمل

يسجّل هذا الملف خادمًا واحدًا لكل وسيلة نقل:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/home/me/projects"],
      "timeout": 30000
    },
    "issues": {
      "command": "node",
      "args": ["./mcp/issues-server.js"],
      "cwd": "/home/me/work/tracker",
      "env": { "ISSUES_TOKEN": "$ISSUES_TOKEN" },
      "includeTools": ["search_issues", "get_issue"]
    },
    "docs-search": {
      "httpUrl": "https://mcp.example.com/mcp",
      "headers": { "Authorization": "Bearer abc123" },
      "timeout": 15000
    },
    "legacy-events": {
      "url": "http://localhost:8080/sse"
    }
  }
}

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

وإليك وظيفة كل حقل:

أبقِ الأسرار خارج الملف

داخل كتلة env، يوسّع Gemini CLI القيمتين $NAME و${NAME} على كل المنصات، وكذلك %NAME% على Windows. ويصبح المتغير غير المضبوط سلسلة نصية فارغة دون أي تحذير. والنتيجة خادم يبدأ ثم يفشل في المصادقة، وهذا يبدو خللًا في الخادم بينما هو في الحقيقة خطأ إملائي في اسم متغير.

ملف المشروع يُحفظ عادةً في المستودع، فأشِر إلى المتغيرات ولا تلصق أي سر فيه أبدًا. التوسيع موثّق لكتلة env، لذا إن أردت رمزًا داخل headers، فتحقق من أن إصدار CLI لديك يوسّعه، أو أبقِ ذلك الإدخال في نطاق المستخدم حيث لا يصل إلى نظام التحكم بالإصدارات.

تقييد الوصول وإدارة المصادقة

يمنح توصيل خادم النموذج مجموعة جديدة من القدرات. قرّر مقدار ما تريده منها قبل الأمر النصي الأول.

تصفية الأدوات لكل خادم

لنفترض أن الخادم يعرض search_issues وget_issue وdelete_issue. تريد الأولى والثانية ولا تريد الثالثة أبدًا:

"issues": {
  "command": "node",
  "args": ["./mcp/issues-server.js"],
  "includeTools": ["search_issues", "get_issue"],
  "excludeTools": ["delete_issue"]
}

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

تأخذ excludeTools الأولوية، فالأداة المدرجة في القائمتين تكون معطّلة. ويمكنك كذلك تصفية خوادم كاملة من المستوى الأعلى في settings.json:

"mcp": {
  "allowed": ["issues", "filesystem"],
  "excluded": ["experimental-server"]
}

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

عند ضبط mcp.allowed، لا يتصل إلا الخوادم المسمّاة هناك. أما mcp.excluded فيحجب الخوادم التي تضعها في القائمة.

استخدم الثقة بحذر

افتراضيًا، يسأل Gemini CLI قبل تشغيل أي أداة. وضبط "trust": true، أو تمرير --trust عند إضافة خادم، يوقف كل التأكيدات لذلك الخادم. وهذا معقول لخادم للقراءة فقط كتبته بنفسك. أما لأي شيء يمكنه كتابة الملفات، أو إرسال الرسائل، أو تشغيل الأوامر، فهو فكرة سيئة، لأن أمرًا نصيًا واحدًا سيئًا قد يشغّله دون أن تراه أولًا.

OAuth عبر /mcp auth

تحتاج كثير من الخوادم المستضافة إلى تسجيل الدخول. داخل CLI، شغّل /mcp auth لعرض الخوادم التي تدعم OAuth، ثم صادق على واحد منها باسمه:

/mcp auth docs-search

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

يفتح CLI المتصفح، ويُكمل التدفق، ويخزّن الرمز في ~/.gemini/mcp-oauth-tokens.json. تُجدَّد الرموز المنتهية تلقائيًا. وإذا لم ينشر الخادم تفاصيل OAuth الخاصة به، فأضف كتلة oauth بنفسك:

"oauth": {
  "enabled": true,
  "clientId": "gemini-cli-client",
  "authorizationUrl": "https://auth.example.com/oauth/authorize",
  "tokenUrl": "https://auth.example.com/oauth/token",
  "scopes": ["mcp:read"]
}

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

الترويسات الثابتة وبيانات اعتماد Google

ليست كل الخوادم تستخدم OAuth. يوضع رمز bearer ثابت في headers، كما رأيت سابقًا. أما الخدمات على Google Cloud، فيقبل الحقل authProviderType القيمة google_credentials، إضافةً إلى service_account_impersonation مع targetServiceAccount. وبالنسبة للخوادم الواقعة خلف Identity-Aware Proxy، أضف targetAudience مع معرّف عميل OAuth. ويعمل المزوّد الافتراضي مع معظم الخوادم الأخرى، فاترك الحقل كما هو إلا إذا احتجت إلى أحد هذه الخيارات.

تحقّق من أن كل شيء يعمل

حرّر الملف، ثم شغّل /mcp reload. وإذا ما زال CLI يعرض الإعدادات القديمة بعد ذلك، فأعد تشغيل الجلسة.

التحقق عبر أوامر /mcp

خارج الجلسة، يعطيك gemini mcp list نظرة عامة على الاتصال نفسها من الشل.

كيف تظهر أسماء الأدوات

تعرض الإصدارات الحديثة أدوات MCP باسم مؤهّل بالكامل بصيغة mcp_<server>_<tool>. فالأداة search_issues على خادم اسمه issues تصبح mcp_issues_search_issues. وتصف مقالات أقدم بادئة server__tool، وتُستخدم عندما يعرض خادمان أداة بالاسم نفسه. وإذا رأيت أسلوبًا في درس وآخر على شاشتك، فمن المرجح أنك على إصدار مختلف.

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

Use the issues server to list open bugs labelled regression, newest first.

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

يعرض CLI الأداة التي ينوي استدعاءها ويطلب التأكيد، ما لم تضبط trust.

إصلاح الخوادم التي لا تتصل

ابدأ بالفحوصات البسيطة، فهي تحل معظم الحالات:

1. شغّل command وargs بالضبط في طرفية عادية. إن فشل هناك، فسيفشل داخل CLI.
2. تأكد أن cwd موجود وأن node أو npx أو python3 موجود في PATH.
3. ابدأ CLI باستخدام --debug واقرأ أخطاء الاتصال.
4. افحص stderr الخاص بالخادم بحثًا عن تتبّعات الأخطاء.
5. شغّل /mcp reload بعد كل تعديل، وأعد تشغيل CLI إذا بدت الإعدادات القديمة عالقة.

Disconnected في المجلدات غير الموثوقة

هذه الحالة توقع الناس فيها باستمرار. في مجلد لم تعتمده ثقةً، لا يتصل Gemini CLI بأي خادم MCP، ويتجاهل .gemini/settings.json الخاص بالمشروع تمامًا. يُقرأ ملف نطاق المستخدم، لكن خوادم المشروع لا تظهر ببساطة.

شغّل /permissions داخل CLI لاعتماد المجلد، أو أجب على مربع الثقة عند فتحه لأول مرة. يُحفظ الاختيار في ~/.gemini/trustedFolders.json. وفي التشغيلات بلا واجهة، تسرد الوثائق العلامة --skip-trust والمتغير GEMINI_CLI_TRUST_WORKSPACE=true.

المهلات والأعطال الصامتة

بعض الأعطال لا تعطي أي خطأ على الإطلاق:

• لا توجد أدوات في القائمة: الخادم متصل لكنه لم يسجّل شيئًا، أو أن مخططات أدواته ليست JSON Schema صالحة. تحقّق من /mcp schema.
• تتوقف استدعاءات الأدوات عن الاستجابة: المهلة الافتراضية عشر دقائق. اخفض timeout للخوادم البعيدة المتقلبة، أو ارفعها للمهام البطيئة مثل الاستعلامات الكبيرة.
• أخطاء مصادقة بعد بدء نظيف: ابحث عن متغير غير مضبوط في env. لقد توسّع إلى سلسلة نصية فارغة.
• أداة مفقودة من القائمة: تحقّق من includeTools وexcludeTools، وقائمة mcp.allowed في المستوى الأعلى.

💡 اختبار سريع للتأكد: أضف خادم stdio صغيرًا أولًا، واجعله متصلًا، ثم أضف الخوادم البعيدة. كل خادم جديد احتمال إضافي للفشل، لذا أضفها واحدًا تلو الآخر.

صِغ الإعدادات بمساعدة Gemini على Picasso IA

يمكنك استخدام نموذج لغوي لصياغة الأجزاء المملة من الإعدادات، وتستضيف Picasso IA عدة نماذج من Gemini يمكنك فتحها في المتصفح. إليك سير عمل يعمل جيدًا:

1. افتح صفحة Gemini 3.5 Flash للمسودات السريعة. أما للملفات الطويلة ذات الخوادم المتعددة أو المصادقة المعقدة، فجرّب Gemini 3.1 Pro. وGemini 3 Flash خيار آخر للتكرار السريع.
2. الصق قسم الإعداد من ملف README الخاص بخادم MCP، ثم أضف قيودك: نظام التشغيل، والنطاق، والمتغير البيئي الذي يحمل الرمز.
3. اطلب مخرجين: إدخال settings.json والأمر المكافئ gemini mcp add. واطلب من النموذج استخدام مراجع $VARIABLE بدلًا من الأسرار الحرفية.
4. تحقق من الإجابة مقابل جدول الحقول أعلاه. يجب أن يوجد واحد فقط من command أو url أو httpUrl، وكل اسم في includeTools يجب أن يطابق ما يطبعه /mcp desc.
5. الصق الإدخال في ملفك وشغّل /mcp reload.

💡 تعامل مع المسودة كمحاولة أولى. قد يخترع النموذج حقلًا يبدو صحيحًا. الجداول في هذا المقال والوثائق الرسمية هي مرجعك الموثوق.

أنشئ صورك الخاصة على Picasso IA

إعداد MCP جيد ليس سوى نصف سير عمل مطوّر منظم. والنصف الآخر هو المواد المحيطة به: لافتات README، ورسوم الدروس التعليمية، وبطاقات التواصل الاجتماعي، والصور الخاصة بالمقال الذي يشرح إعدادك.

تتيح لك Picasso IA توليد هذه الصور في دقائق قليلة. جرّب Seedream 4.5 للمشاهد الواقعية كالصور الفوتوغرافية التفصيلية، أو GPT Image 2 حين تحتاج إلى نص نظيف داخل الصورة، أو Nano Banana 2 Lite للمسودات السريعة. اكتب أمرًا نصيًا قصيرًا، وولّد عدة صور بديلة، واحتفظ بالصورة التي تناسب صفحتك.

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