Nano Banana MCP Server cho Claude, Cursor và Gemini CLI

Một máy chủ Model Context Protocol từ xa cung cấp toàn bộ bộ công cụ tạo của BananaBanana dưới dạng các công cụ dành cho agent: hình ảnh Google Nano Banana 2 Lite / 2 / 2.1 / Pro (chỉ từ $0.03), video Veo 3.1 / Fast / Lite và Gemini Omni Flash, Wan 3.0 có âm thanh ($0.09–1.00). Agent của bạn sẽ thấy giá trực tiếp, xác nhận chi phí trước khi chạy các tác vụ tốn kém, và mọi lượt tạo sẽ được lưu vào cùng một lịch sử và số dư như trên trang web.

• Endpoint: https://bananabanana.pro/api/mcp (Streamable HTTP)
• Xác thực: đăng nhập bằng OAuth 2.1 (claude.ai và các client dạng connector khác) hoặc khóa API Bearer từ hồ sơ của bạn
• Giới hạn tần suất: 20 lượt gọi công cụ mỗi phút cho mỗi khóa; tùy chọn giới hạn chi tiêu hàng ngày cho từng khóa
• Không có MCP client? Cùng một endpoint là JSON-RPC thuần túy qua HTTPS — gọi nó từ curl, Python hoặc TypeScript mà không cần bất kỳ SDK nào
• Các lượt tạo thất bại hoặc bị chặn bởi bộ lọc sẽ tự động được hoàn tiền
• Mở tài liệu, server.json và sao chép các ví dụ về client trong kho lưu trữ GitHub bananabanana-mcp

1. Tạo tài khoản và nạp số dư. 2. Trong Hồ sơ → MCP API Keys tạo một khóa (chỉ hiển thị một lần). 3. Thêm máy chủ vào client của bạn:

claude.ai, Claude Desktop, di động (OAuth — không cần sao chép gì)

Settings → Connectors → Add custom connector, dán https://bananabanana.pro/api/mcp rồi nhấn Connect. Claude tự đăng ký, bạn phê duyệt quyền truy cập trên màn hình BananaBanana, và các lần tạo sẽ trừ vào tài khoản bạn đã đăng nhập.

Settings → Connectors → Add custom connector
URL: https://bananabanana.pro/api/mcp
→ Add → Connect → approve access on bananabanana.pro

Cùng luồng đó hoạt động với mọi client hỗ trợ ủy quyền MCP — MCP Inspector, connector web của ChatGPT và Grok, Claude Code. Ứng dụng đã kết nối được liệt kê trong hồ sơ và có thể ngắt bất cứ lúc nào.

Claude Code

# with an API key
claude mcp add --transport http bananabanana https://bananabanana.pro/api/mcp \
  --header "Authorization: Bearer bb_live_YOUR_KEY"

# or with OAuth — no key, sign in in the browser
claude mcp add --transport http bananabanana https://bananabanana.pro/api/mcp
# then run /mcp inside Claude Code and pick "Authenticate"

Claude Desktop

Thêm vào claude_desktop_config.json (Settings → Developer → Edit Config); yêu cầu Node.js cho cầu nối mcp-remote:

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

Cursor

Thêm vào ~/.cursor/mcp.json (toàn cục) hoặc .cursor/mcp.json trong dự án; để không để lộ khóa trong tệp, hãy sử dụng ${env:BB_API_KEY} thay vì giá trị trực tiếp:

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

Hướng dẫn đầy đủ về Cursor, bao gồm các lưu ý nhỏ và bản demo khóa trực tiếp: Tạo hình ảnh trong Cursor.

VS Code / GitHub Copilot

Thêm vào .vscode/mcp.json trong không gian làm việc (hoặc settings.json người dùng của bạn); VS Code sẽ nhắc nhập khóa một lần và lưu trữ khóa đó dưới dạng mã hóa:

{
  "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
    }
  ]
}

Hướng dẫn đầy đủ về VS Code / Copilot, bao gồm các lưu ý nhỏ và bản demo khóa trực tiếp: Tạo hình ảnh trong VS Code: Hướng dẫn thiết lập Copilot MCP.

Windsurf

Thêm vào ~/.codeium/windsurf/mcp_config.json:

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

Windsurf MCP Setup: Generate Images in Cascade

Cline

{
  "mcpServers": {
    "bananabanana": {
      "type": "streamableHttp",
      "url": "https://bananabanana.pro/api/mcp",
      "headers": {
        "Authorization": "Bearer bb_live_YOUR_KEY"
      },
      "disabled": false,
      "autoApprove": ["list_models", "get_account", "get_result"]
    }
  }
}

Cline MCP Server: Generate Images From Your Editor

Bất kỳ MCP client nào khác (JSON-RPC thuần)

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"}

Mọi phương thức trừ ping và các danh sách discovery (tools/list, prompts/list, resources/list) đều cần thông tin xác thực — kể cả initialize: một lần bắt tay chưa xác thực sẽ trả về 401 kèm challenge WWW-Authenticate. Sự bất đối xứng này là có chủ đích, không phải lỗi: chính challenge đó giúp client dạng connector nhận ra máy chủ này dùng OAuth. Việc đọc danh mục công cụ mà không có khóa vẫn hoạt động.

Bạn muốn xem hướng dẫn chi tiết? Bài viết hướng dẫn Tạo hình ảnh trong Claude Code sẽ bao gồm việc thiết lập Claude từ đầu đến cuối, với bốn trường hợp sử dụng thực tế và chi phí thực tế của chúng.

MCP là một giao thức mở: bất kỳ client nào hỗ trợ Streamable HTTP và có thể đính kèm header Authorization đều có thể kết nối. Trạng thái hiện tại, được xác minh theo tài liệu chính thức của từng nhà cung cấp (lần kiểm tra cuối cùng vào tháng 8 năm 2026):

Ví dụ về Codex — thêm vào ~/.codex/config.toml và xuất BB_API_KEY=bb_live_…:

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

Hướng dẫn đầy đủ về Codex — CLI, tiện ích mở rộng IDE và ChatGPT desktop từ một cấu hình duy nhất, cùng các lưu ý nhỏ và bản demo khóa trực tiếp: Thiết lập Codex MCP: Hình ảnh và Video từ một config.toml.

Không sử dụng MCP client? Bạn không cần nó — và bạn cũng không cần bất kỳ SDK nào. Máy chủ là JSON-RPC 2.0 thuần túy qua HTTPS: một endpoint POST, một Bearer header, một phản hồi JSON duy nhất. Nó là stateless (không lưu trạng thái), vì vậy không có quá trình bắt tay phiên cần quản lý — tools/call hoạt động như một yêu cầu đầu tiên từ curl, Python, TypeScript hoặc bất kỳ công cụ nào khác có thể gửi HTTP.

curl

# start an image generation (charges one image, $0.03 on the default Lite 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

Chỉ dùng thư viện requests — không cần thư viện 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

Không có phần phụ thuộc — tích hợp sẵn fetch (Node 18+, Deno, Bun, trình duyệt):

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);

Những chi tiết quan trọng khi bạn viết mã nguồn:

• Mỗi phản hồi của công cụ đều mang cùng một JSON hai lần: result.structuredContent máy có thể đọc và một khối văn bản trong result.content — hãy phân tích cú pháp khối nào dễ dàng hơn cho bạn.
• Video (và các đợt tạo nhiều hình ảnh) là cuộc gọi hai bước: lệnh gọi generate_video đầu tiên trả về báo giá và không tính phí; hãy lặp lại lệnh gọi đó với confirm_cost được đặt thành số tiền được báo giá để bắt đầu.
• Truyền một khóa idempotency_key trên các cuộc gọi tạo — việc thử lại mạng sẽ không bao giờ tính phí hai lần.
• tools/list hoạt động mà không cần khóa, vì vậy bạn can khám phá các schema đầy đủ trước khi tạo tài khoản. Các lượt gọi công cụ được giới hạn ở mức 20 lượt mỗi phút cho mỗi khóa.

• Giá được cung cấp trực tiếp qua list_models — cùng nguồn dữ liệu mà trang web sử dụng.
• Mỗi lượt gọi video (và đợt tạo nhiều hình ảnh) trước tiên sẽ trả về báo giá và không tính phí; agent lặp lại lượt gọi với confirm_cost để thực sự bắt đầu.
• Mọi kết quả đều bao gồm cost_charged_usd and balance_remaining_usd.
• Các lỗi hệ thống đầu nguồn và từ chối do bộ lọc nội dung sẽ được hoàn tiền tự động — cùng chính sách như ứng dụng web.
• Tùy chọn idempotency_key đảm bảo việc thử lại cuộc gọi không bao giờ bị tính phí hai lần.

• Các URL kết quả được ký số và có giá trị trong 24 giờ; bản thân tệp phương tiện vẫn nằm trong tài khoản của bạn — hãy gọi lại get_result để lấy liên kết mới hoặc tải xuống từ trang web.
• Các API key được lưu trữ dưới dạng băm và chỉ hiển thị một lần khi tạo; bạn có thể thu hồi chúng bất kỳ lúc nào trong hồ sơ cá nhân của mình.
• Kết nối OAuth dùng access token một giờ với refresh token xoay vòng, chỉ lưu dạng băm và chỉ hợp lệ với máy chủ này; ngắt ứng dụng trong hồ sơ sẽ vô hiệu token ngay lập tức.
• Nhật ký sử dụng cho từng khóa (công cụ, mô hình, chi phí, xem trước prompt) có thể xem được trong Hồ sơ → MCP API Keys.
• Các lượt tạo qua MCP xuất hiện trong cùng một lịch sử tạo và phân tích như lượt tạo trên web.

x402 là giao thức mở cho phép agent trả tiền cho một yêu cầu bằng stablecoin. Đây là endpoint tách biệt với máy chủ MCP: POST /api/x402. Không cần tài khoản, khóa API hay nạp tiền.

1. Gửi tên công cụ và các tham số. Máy chủ trả về 402 kèm giá chính xác của lượt gọi đó.
2. Ký thanh toán bằng USDC trên mạng Base rồi gửi lại yêu cầu với header X-PAYMENT.
3. Hình ảnh và giọng nói được trả về ngay trong phản hồi. Video trả về job_id; kiểm tra kết quả miễn phí qua GET /api/x402/result/{jobId}.

Công cụ khả dụng: generate_image, generate_speech, generate_video. Giá giống như trên studio web và qua MCP; lượt gọi có giá bằng giá tạo nội dung, không có mức nạp tối thiểu.

Nếu video đã trả tiền bị lỗi, người trả nhận một token tín dụng cùng giá trị, có hiệu lực 90 ngày. Gửi nó dưới dạng refund_token trong lượt gọi sau. Thanh toán không được hoàn on-chain. Danh mục dạng máy đọc với giá hiện tại nằm ở GET /api/x402.