BananaBanana MCP Server

خادم Model Context Protocol عن بُعد يتيح الوصول الكامل إلى تقنيات توليد BananaBanana كأدوات للوكلاء: صور Google Nano Banana 2 Lite / 2 / Pro (تبدأ من $0.03)، وفيديوهات Veo 3.1 / Fast / Lite، ونموذج Gemini Omni Flash مع الصوت (بسعر ثابت قدره $1.00). يرى وكيلك الأسعار المباشرة، ويؤكد التكاليف قبل العمليات المكلفة، وتُسجّل جميع عمليات التوليد في نفس السجل والرصيد على الموقع.

• نقطة النهاية: https://bananabanana.pro/api/mcp (Streamable HTTP)
• المصادقة: مفتاح Bearer API من ملفك الشخصي (دعم OAuth 2.1 مخطط له قريباً)
• حد الاستخدام: 20 استدعاء أداة في الدقيقة لكل مفتاح؛ مع حد إنفاق يومي اختياري لكل مفتاح
• ليس لديك عميل MCP؟ نقطة النهاية نفسها هي بروتوكول JSON-RPC عادي عبر HTTPS — يمكنك استدعاؤها عبر curl أو Python أو TypeScript دون أي SDK
• عمليات التوليد الفاشلة أو التي تم تصفيتها تُسترد مبالغها تلقائيًا
• افتح المستندات وserver.json وانسخ أمثلة العملاء من مستودع bananabanana-mcp على GitHub

1. أنشئ حسابًا واشحن رصيدك. 2. في الملف الشخصي ← MCP API Keys أنشئ مفتاحًا (يظهر مرة واحدة). 3. أضف الخادم إلى عميلك:

Claude Code

claude mcp add --transport http bananabanana https://bananabanana.pro/api/mcp \
  --header "Authorization: Bearer bb_live_YOUR_KEY"

Claude Desktop

أضف إلى claude_desktop_config.json (عبر Settings ← Developer ← Edit Config)؛ يتطلب تثبيت Node.js من أجل جسر mcp-remote:

{
  "mcpServers": {
    "bananabanana": {
      "command": "npx",
      "args": [
        "-y", "mcp-remote", "https://bananabanana.pro/api/mcp",
        "--header", "Authorization: Bearer bb_live_YOUR_KEY"
      ]
    }
  }
}

Cursor

أضف إلى ~/.cursor/mcp.json (عام) أو .cursor/mcp.json في المشروع؛ لإبقاء المفتاح خارج الملف، استخدم ${env:BB_API_KEY} بدلاً من القيمة الصريحة:

{
  "mcpServers": {
    "bananabanana": {
      "url": "https://bananabanana.pro/api/mcp",
      "headers": {
        "Authorization": "Bearer bb_live_YOUR_KEY"
      }
    }
  }
}

دليل كامل لـ Cursor، بما في ذلك الميزات الاستثنائية وتجريب المفاتيح المباشرة: توليد الصور في Cursor.

VS Code / GitHub Copilot

أضف إلى .vscode/mcp.json في مساحة العمل (أو settings.json الخاص بالمسخدم)؛ يطلب VS Code المفتاح مرة واحدة ويخزنه مشفرًا:

{
  "servers": {
    "bananabanana": {
      "type": "http",
      "url": "https://bananabanana.pro/api/mcp",
      "headers": {
        "Authorization": "Bearer ${input:bb-api-key}"
      }
    }
  },
  "inputs": [
    {
      "type": "promptString",
      "id": "bb-api-key",
      "description": "BananaBanana API key (bb_live_…)",
      "password": true
    }
  ]
}

دليل كامل لـ VS Code / Copilot، بما في ذلك الميزات الاستثنائية وتجريب المفاتيح المباشرة: توليد الصور في VS Code: دليل إعداد Copilot MCP.

Windsurf

أضف إلى ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "bananabanana": {
      "serverUrl": "https://bananabanana.pro/api/mcp",
      "headers": {
        "Authorization": "Bearer bb_live_YOUR_KEY"
      }
    }
  }
}

أي عميل MCP آخر (JSON-RPC مباشر)

POST https://bananabanana.pro/api/mcp
Authorization: Bearer bb_live_YOUR_KEY
Content-Type: application/json
Accept: application/json, text/event-stream

{"jsonrpc":"2.0","id":1,"method":"tools/list"}

هل تفضل دليلاً تعليميًا؟ يغطي الشرح توليد الصور في Claude Code إعداد Claude بالكامل خطوة بخطوة، مع أربع حالات استخدام حقيقية وتكاليفها الفعلية.

بروتوكول MCP هو بروتوكول مفتوح: يتصل أي عميل يدعم Streamable HTTP ويمكنه إرفاق ترويسة Authorization. الحالة الحالية، تم التحقق منها وفقًا للمستندات الرسمية لكل جهة (آخر تحديث في يوليو 2026):

مثال Codex — أضف إلى ~/.codex/config.toml وقم بتصدير BB_API_KEY=bb_live_…:

[mcp_servers.bananabanana]
url = "https://bananabanana.pro/api/mcp"
bearer_token_env_var = "BB_API_KEY"

دليل كامل لـ Codex — سطر الأوامر CLI، إضافة بيئة التطوير IDE وتطبيق ChatGPT للكمبيوتر من تكوين واحد، مع الميزات الاستثنائية وعرض حي للمفاتيح: إعداد Codex MCP: صور وفيديو من ملف config.toml واحد.

ألا تستخدم عميل MCP؟ لا تحتاج إلى واحد — كما أنك لا تحتاج إلى SDK أيضًا. الخادم يعمل ببروتوكول JSON-RPC 2.0 عادي عبر HTTPS: نقطة نهاية POST واحدة، وترویسة Bearer، واستجابة JSON واحدة. إنه عديم الحالة (stateless)، لذا ليس هناك اتصال مصافحة (session handshake) لِإدارته — يعمل tools/call كأول طلب من curl أو Python أو TypeScript أو أي شيء آخر يمكنه إرسال طلبات HTTP.

curl

# start an image generation (charges one image, $0.06 on the default model)
curl -s https://bananabanana.pro/api/mcp \
  -H "Authorization: Bearer bb_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{
        "name":"generate_image",
        "arguments":{"prompt":"studio photo of a ceramic mug on linen, soft daylight"}}}'

# → result.structuredContent.job_id = "cmxy…"

# fetch the result (long-polls server-side up to 30 s; free)
curl -s https://bananabanana.pro/api/mcp \
  -H "Authorization: Bearer bb_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{
        "name":"get_result",
        "arguments":{"job_id":"cmxy…","wait_seconds":30}}}'

Python

مكتبة requests فقط — دون الحاجة لمكتبة MCP:

import requests

MCP = "https://bananabanana.pro/api/mcp"
HEADERS = {"Authorization": "Bearer bb_live_YOUR_KEY"}

def call(tool, **args):
    r = requests.post(MCP, headers=HEADERS, json={
        "jsonrpc": "2.0", "id": 1, "method": "tools/call",
        "params": {"name": tool, "arguments": args},
    })
    r.raise_for_status()
    return r.json()["result"]["structuredContent"]

job = call("generate_image", prompt="watercolor painting of a lighthouse at dawn")

result = call("get_result", job_id=job["job_id"], wait_seconds=30)
while result["status"] == "processing":
    result = call("get_result", job_id=job["job_id"], wait_seconds=30)

print(result["files"][0]["url"], "cost:", result["cost_charged_usd"])

TypeScript / Node.js

بدون أي تبعيات إضافية — باستخدام fetch المدمجة (Node +18، Deno، Bun، والمتصفحات):

const MCP = "https://bananabanana.pro/api/mcp";

async function call(tool: string, args: Record<string, unknown>) {
  const res = await fetch(MCP, {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.BB_API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      jsonrpc: "2.0", id: 1, method: "tools/call",
      params: { name: tool, arguments: args },
    }),
  });
  const { result } = await res.json();
  return result.structuredContent;
}

const job = await call("generate_image", {
  prompt: "isometric 3D render of a tiny greenhouse at golden hour",
});

let out = await call("get_result", { job_id: job.job_id, wait_seconds: 30 });
while (out.status === "processing") {
  out = await call("get_result", { job_id: job.job_id, wait_seconds: 30 });
}
console.log(out.files[0].url, "cost:", out.cost_charged_usd);

تفاصيل تهمك عند كتابة البرمجيات:

• تتضمن كل استجابة أداة نفس كائن JSON مرتين: جزء قابل للقراءة آليًا result.structuredContent وكتلة نصية في result.content — قم بتحليل أيهما أسهل لك.
• عمليات توليد الفيديو (ودفعات الصور المتعددة) تتم على خطوتين: أول استدعاء لـ generate_video يعيد عرض سعر ولا يخصم شيئًا؛ كرره مع تعيين confirm_cost على القيمة المعروضة للبدء.
• مرر مفتاح عدم التكرار idempotency_key في طلبات التوليد — ولن تؤدي عمليات إعادة محاولة الشبكة أبدًا إلى الخصم المزدوج.
• يعمل tools/list بدون مفتاح، مما يتيح لك استكشاف المخططات (schemas) الكاملة قبل إنشاء حساب. تقتصر استدعاءات الأدوات على 20 استدعاء في الدقيقة لكل مفتاح.

• تُقدّم الأسعار مباشرة عبر list_models — وهو نفس المصدر الذي يستخدمه الموقع الإلكتروني.
• كل استدعاء لتوليد فيديو (ودفعة صور متعددة) يعيد أولاً عرض سعر ولا يخصم شيئًا؛ يكرر الوكيل الاستدعاء مع confirm_cost للبدء.
• تتضمن كل نتيجة قيمتي cost_charged_usd و balance_remaining_usd.
• يتم استرداد الأموال تلقائيًا في حالات الفشل في الخوادم البعيدة أو الرفض بسبب فلاتر المحتوى — وهي نفس السياسة المتبعة في تطبيق الويب.
• يضمن مفتاح عدم التكرار الاختياري idempotency_key عدم الخصم المزدوج عند إعادة المحاولة.

→ generate_video {"prompt": "drone shot over a misty pine forest", "model": "veo-3.1-fast"}
← {"status": "confirmation_required", "quoted_cost_usd": 0.70, ...}
→ generate_video {..., "confirm_cost": 0.70}
← {"job_id": "cmxy…", "status": "processing", "cost_charged_usd": 0.70, "balance_remaining_usd": 12.40}
→ get_result {"job_id": "cmxy…"}
← {"status": "completed", "files": [{"url": "https://…"}], "cost_charged_usd": 0.70}

• روابط النتائج موقعة وصالحة لمدة 24 ساعة؛ وتبقى الوسائط نفسها في حسابك — استدعِ get_result مجددًا للحصول على روابط جديدة، أو قم بتنزيلها من الموقع الإلكتروني.
• تُخزّن مفاتيح API في شكل هاش (مشفّرة) وتظهر مرة واحدة فقط عند الإنشاء؛ ويمكنك إلغاؤها في أي وقت من ملفك الشخصي.
• سجل الاستخدام لكل مفتاح (الأداة، النموذج، التكلفة، ومعاينة الوصف) مرئي في الملف الشخصي ← MCP API Keys.
• تظهر عمليات توليد MCP في نفس سجل عمليات التوليد والتحليلات الخاصة بالتوليد عبر الويب.