توليد الصور في Gemini CLI: إعداد خادم MCP

يُعد Gemini CLI وكيل طرفية مفتوح المصدر من Google، وبروتوكول MCP هو المعيار الذي يعتمد عليه للوصول إلى الأدوات الخارجية. عند توجيهه نحو خادم MCP بعيد، تصبح جلسة الدردشة نفسها التي تعدل الكود قادرة على إنشاء الصور والفيديو والصوت، وحفظ الملفات مباشرة في مسار عملك.

الإجابة السريعة: نفّذ الأمر gemini mcp add --transport http --scope user bananabanana https://bananabanana.pro/api/mcp -H "Authorization: Bearer $BB_KEY"، ووافق على توثيق المجلد عندما يطلب الطرفي ذلك، ثم تحقق عبر gemini mcp list لظهور الحالة باللون الأخضر Connected. تبدأ تكلفة الصور من $0.03 لكل عملية توليد تُخصم من رصيدك.

تم اختبار جميع الخطوات أدناه مع Gemini CLI 0.55.1 في 17 أغسطس 2026 باستخدام مفتاح bb_live_… صالح. وحيثما يختلف التوثيق الرسمي عن سلوك الأداة الفعلي، تم توضيح ذلك بوضوح.

خطوات الإعداد المباشرة

أمران فقط. الأول يسجل الخادم:

export BB_KEY=bb_live_…   # create one at https://bananabanana.pro/profile
 
gemini mcp add --transport http --scope user \
  bananabanana https://bananabanana.pro/api/mcp \
  -H "Authorization: Bearer $BB_KEY"

والثاني يتحقق من الاتصال:

gemini mcp list
# ✓ bananabanana: https://bananabanana.pro/api/mcp (http) - Connected

إذا ظهرت لك الحالة Disabled بدلاً من Connected، فاقرأ القسم التالي قبل تغيير أي إعدادات أخرى؛ إذ استغرق مني هذا التفصيل خمس دقائق لاكتشافه.

خمس ملاحظات لم يذكرها التوثيق الرسمي

توثيق المجلد يُعطل كل شيء بصمت. إذا نفذت gemini mcp list داخل مسار غير موثوق به لدى الطرفي، فستظهر الرسالة التالية:

Warning: MCP servers are configured but disabled because this folder is untrusted.
User-level servers are also suppressed in untrusted folders to prevent accidental side-effects.

○ bananabanana: https://bananabanana.pro/api/mcp (http) - Disabled

لاحظ السطر الثاني: حتى الخوادم المحددة بنطاق --scope user تظل معطلة. تطلب الأداة تأكيد الثقة عند التشغيل التفاعلي الأول؛ وفي السكربتات الآلية، يُحفظ قرار الثقة في ~/.gemini/trustedFolders.json كخريطة مسارات مع القيمة TRUST_FOLDER. هذا إجراء أمني منطقي، لكن رسالة "Disabled" لا توضح أن السبب يعود للمجلد.

أمر gemini mcp add يكتب url بدلاً من httpUrl. يصف التوثيق الرسمي معيار httpUrl لبروتوكول Streamable HTTP، لكن ما أنشأه الإصدار 0.55.1 في الواقع هو:

{
  "mcpServers": {
    "bananabanana": {
      "url": "https://bananabanana.pro/api/mcp",
      "type": "http",
      "headers": { "Authorization": "Bearer $BB_KEY" }
    }
  }
}

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

النطاق الافتراضي هو project، وتُحفظ فيه المفاتيح. إذا لم تُحدد --scope user، فسيُكتب المفتاح داخل .gemini/settings.json في المستودع. وبمجرد تنفيذ git add . سيظهر المفتاح في سجل الالتزامات. استخدم دائماً --scope user أو مرر الترويسة كمتغير بيئة كما هو موضح في المثال.

تعويض المتغير $BB_KEY يعمل، ولكنه يفشل بصمت. عند تصدير المتغير تظهر الحالة Connected. وإذا فتحت طرفية جديدة دون تصديره، يُظهر الإعداد نفسه Disconnected دون توضيح سبب متعلق بالمصادقة. يُنصح بإضافة سطر التصدير إلى ملف تكوين الشل لديك.

يستطلع Gemini CLI اتصال SSE ويتلقى رد 405. عند مراجعة سجلات الخادم أثناء الاتصال، يكون التسلسل كالآتي: POST initialize (200)، وPOST notification (202)، وGET /api/mcp (405)، وPOST tools/list (200). طلب GET هو محاولة من الطرفي لفتح قناة Server-Sent Events على خادم عديم الحالة. يفشل الطلب برمز 405، لكن الطرفي يتجاهله ويكمل عمله بصورة طبيعية. إذا كنت تشغل خادم MCP خاصاً بك، فلا تقلق بشأن رمز 405 هذا.

الأدوات المتاحة وتكلفتها

تتوفر تسع أدوات في الجلسة، وهي الأدوات نفسها الموضحة في مرجع الأدوات. أربع منها مجانية الاستدعاء: list_models، وget_account، وget_result، وlist_generations. أما بقية الأدوات فتُخصم تكلفتها لكل عملية توليد من رصيد حسابك.

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

تمنح عمليات شحن الرصيد مكافآت إضافية: 5% بدءاً من $50، و10% بدءاً من $100، ويضيف الرمز الترويجي النشط 10% إضافية من قيمة الإيداع. إيداع $100 مع رمز ترويجي يمنحك رصيداً بقيمة $120.

توليد صور Nano Banana عبر Gemini: ما الفائدة؟

قد يبدو استدعاء Gemini CLI لنموذج صور Gemini عبر خادم وسيط مساراً غير مباشر. هناك خيار مباشر بالطبع: إنشاء حساب فوترة على Google Cloud، وتفعيل واجهات برمجة النماذج، وإدارة بيانات الاعتماد والحصص حسب المنطقة. هذا خيار مناسب إذا كان عملك بناء وإدارة بنية تحتية سحابية.

أما خدمتنا فتلبي احتياجاً آخر: رمز مصادقة واحد، رصيد مسبق الدفع، دون الحاجة لحساب فوترة سحابي، أو تقديم طلبات لرفع الحصص، أو التقيد بمنطقة جغرافية. كما يتيح لك الاتصال نفسه استخدام نماذج الفيديو Veo وOmni وتوليد الصوت TTS بنظام الدفع لكل عملية توليد بدلاً من تكاليف المشاريع. إذا كان هدفك هو الإنتاج والابتكار بدلاً من إدارة المنصات، فهذا هو المسار الأسهل.

عند الاستخدام الضخم للغاية، سيكون المسار السحابي المباشر أقل تكلفة. لكن خدمتنا تتيح لك البدء خلال دقيقتين مع تفادي مفاجآت الفواتير غير المتوقعة.

إذا كنت تستخدم بيئات تطوير أخرى، فإن الخادم نفسه يتكامل مع Claude Code وCursor وCodex بالمفتاح نفسه وملف الإعداد المناسب.

حالة استخدام عملية: رسوم توضيحية للتوثيق

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

الأمر التوجيهي داخل الجلسة:

Read every heading in docs/*.md. For each file, generate a 16:9 illustration matching the page topic, in this style: editorial illustration, pastel paper background, dark ink details, violet and amber accents, no text. Use nano-banana-pro. Save each as docs/img/.png and add the image reference under the page title.

يقرأ الوكيل الملفات، ويستدعي generate_image لكل صفحة، وينتظر النتيجة عبر get_result، ثم ينزل الصور ويدرجها في ملفات markdown. تكلفة اثنتي عشرة صورة بسعر $0.11 تبلغ $1.32، وكل ذلك يكتمل بينما تتناول قهوتك. تم إنشاء جميع الرسوم التوضيحية في هذه المقالة بالمسار نفسه عبر Nano Banana Pro وبوصف موحد للأسلوب الفني.

نصيحتان قبل البدء: أنشئ صورة تجريبية واحدة أولاً للتأكد من ملاءمة الأسلوب (فأي خطأ في الوصف سيكلفك $1.32 بلا فائدة)، واترك خيار --trust معطلاً لتأكيد طلبات الأدوات المدفوعة يدوياً ومنع الحلقات اللانهائية للوكيل.

هل يعمل بروتوكول OAuth كبديل للمفتاح؟

يدعم Gemini CLI بروتوكول OAuth 2.0 للخوادم البعيدة مع ميزة الاكتشاف وأمر /mcp auth. خادمنا هو خادم تخويل كامل بمعيار OAuth 2.1 (تسجيل ديناميكي للعملاء، وتشفير PKCE S256، واكتشاف RFC 9728)، وعملاء مثل Claude Code وclaude.ai يسجلون الدخول بهذه الطريقة دون الحاجة لمفتاح يدوي.

تم اختبار مسار مفتاح API بالكامل وهو يعمل بثبات تام. أما مسار OAuth عبر Gemini CLI فلم يُختبر بشكل منفصل في هذه الجلسة، لذا يُعد متاحاً نظرياً لكنه غير مؤكد تماماً. إنشاء مفتاح API يستغرق عشر ثوانٍ فقط ويظل سارياً دون انتهاء حتى تقوم بإلغائه.

الأسئلة الشائعة

أين يقع ملف الإعدادات؟

في ~/.gemini/settings.json لنطاق المستخدم (user scope)، أو .gemini/settings.json لنطاق المشروع (project scope). أمر gemini mcp add --scope user يكتب في الملف الأول.

لماذا تظهر حالة الخادم Disabled؟

المجلد الحالي غير موثوق به لدى الطرفي. أكد الوثوق عند بدء التشغيل أو أضف المسار إلى ~/.gemini/trustedFolders.json بالقيمة TRUST_FOLDER. الخوادم على مستوى المستخدم تُعطل أيضاً داخل المجلدات غير الموثوقة.

هل يمكنني تقييد الأدوات التي يراها النموذج؟

نعم. استخدم الخيارين --include-tools و--exclude-tools مع أمر gemini mcp add، أو حقلي includeTools وexcludeTools في الإعدادات. قواعد الاستبعاد لها الأولوية على التضمين.

هل يعمل الإعداد في مشروع مشترك مع الفريق؟

قم بتعريف الخادم على مستوى المشروع وضع المفتاح في متغير بيئة دون كتابته صراحة في الملفات. يُنفذ كل مطور export BB_KEY=… بمفتاحه الخاص ويبقى سجل git نظيفاً.

ماذا يحدث إذا فشلت عملية التوليد؟

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

هل تفضل استخدام واجهة رسومية؟ يعمل المولد عبر المتصفح بالنماذج نفسها والرصيد نفسه. وفي الطرفية، ابدأ باستدعاء list_models فور الاتصال: الأداة مجانية، وتعرض الأسعار الحالية، وتؤكد جاهزية الاتصال قبل إنفاق أي سنت.