Nano Banana MCP Server para Claude, Cursor e Gemini CLI

Um servidor remoto Model Context Protocol que expõe todo o ecossistema de geração do BananaBanana como ferramentas para agentes: imagens do Google Nano Banana 2 Lite / 2 / 2.1 / Pro (a partir de $0.03), vídeos do Veo 3.1 / Fast / Lite e Gemini Omni Flash, Wan 3.0 com som ($0.09–1.00). Seu agente visualiza os preços em tempo real, confirma os custos antes de execuções caras, e cada geração é registrada no mesmo histórico e saldo do site.

• Endpoint: https://bananabanana.pro/api/mcp (HTTP Streamable)
• Autenticação: entre com OAuth 2.1 (claude.ai e outros clientes com conectores) ou uma chave API Bearer do seu perfil
• Limite de requisições: 20 chamadas de ferramenta por minuto por chave; limite diário de gastos opcional por chave
• Não usa cliente MCP? O mesmo endpoint é um JSON-RPC simples sobre HTTPS — chame-o via curl, Python ou TypeScript sem a necessidade de qualquer SDK
• Gerações que falharem ou forem filtradas são reembolsadas automaticamente
• Acesse a documentação, o server.json e copie exemplos de clientes no repositório do GitHub bananabanana-mcp

1. Crie uma conta e recarregue seu saldo. 2. Em Perfil → Chaves de API MCP, crie uma chave (exibida apenas uma vez). 3. Adicione o servidor ao seu cliente:

claude.ai, Claude Desktop, celular (OAuth — nada para copiar)

Settings → Connectors → Add custom connector, cole https://bananabanana.pro/api/mcp e clique em Connect. O Claude se registra sozinho, você aprova o acesso numa tela da BananaBanana, e as gerações são cobradas da conta com que você entrou.

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

O mesmo fluxo funciona em qualquer cliente que implemente a autorização MCP: MCP Inspector, conectores web do ChatGPT e do Grok, Claude Code. Os apps conectados aparecem no seu perfil e podem ser desconectados a qualquer momento.

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

Adicione ao claude_desktop_config.json (Settings → Developer → Edit Config); requer Node.js para a ponte mcp-remote:

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

Cursor

Adicione ao ~/.cursor/mcp.json (global) ou .cursor/mcp.json no projeto; para manter a chave fora do arquivo, use ${env:BB_API_KEY} em vez do valor literal:

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

Guia completo do Cursor, incluindo detalhes de funcionamento e uma demonstração com chave ativa: Gere Imagens no Cursor.

VS Code / GitHub Copilot

Adicione ao .vscode/mcp.json no workspace (ou no seu settings.json do usuário); o VS Code solicitará a chave uma vez e a armazenará de forma criptografada:

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

Guia completo do VS Code / Copilot, incluindo detalhes de funcionamento e uma demonstração com chave ativa: Gere Imagens no VS Code: Guia de Configuração do Copilot MCP.

Windsurf

Adicione ao ~/.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

Qualquer outro cliente MCP (JSON-RPC puro)

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

Todos os métodos, exceto ping e as listas de discovery (tools/list, prompts/list, resources/list), exigem credenciais — inclusive initialize: um handshake não autenticado responde 401 com um desafio WWW-Authenticate. A assimetria é deliberada, não um bug: é por esse desafio que um cliente conector descobre que este servidor usa OAuth. Ler o catálogo de ferramentas sem chave continua funcionando.

Prefere um tutorial passo a passo? O tutorial Gere Imagens no Claude Code cobre a configuração do Claude de ponta a ponta, com quatro casos de uso reais e seus respectivos custos.

O MCP é um protocolo aberto: qualquer cliente que suporte HTTP Streamable e consiga anexar um cabeçalho Authorization pode se conectar. Status atual, verificado com base nas documentações oficiais de cada provedor (última verificação em agosto de 2026):

Exemplo do Codex — adicione a ~/.codex/config.toml e exporte BB_API_KEY=bb_live_…:

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

Guia completo do Codex — CLI, extensão de IDE e ChatGPT desktop a partir de uma única configuração, com detalhes de funcionamento e uma demonstração com chave ativa: Configuração do Codex MCP: Imagens e Vídeos a partir de um único config.toml.

Não usa um cliente MCP? Você não precisa de um — e também não precisa de SDK. O servidor é um JSON-RPC 2.0 simples sobre HTTPS: um endpoint POST, um cabeçalho Bearer e uma única resposta JSON. Ele é stateless, portanto não há handshake de sessão para gerenciar — o tools/call funciona logo na primeira requisição usando curl, Python, TypeScript ou qualquer outra ferramenta capaz de enviar requisições 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

Apenas requests — sem biblioteca 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

Zero dependências — fetch nativo (Node 18+, Deno, Bun, navegadores):

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

Detalhes importantes para quando você for criar scripts:

• Toda resposta de ferramenta traz o mesmo JSON duas vezes: o formato legível por máquina result.structuredContent e um bloco de texto em result.content — processe o que for mais fácil.
• Geração de vídeos (e lotes de várias imagens) é um processo de duas etapas: a primeira chamada a generate_video retorna uma estimativa e não cobra nada; repita a chamada enviando em confirm_cost o valor estimado para iniciar.
• Envie uma idempotency_key nas chamadas de geração — tentativas de reenvio por falha de rede nunca cobrarão em duplicidade.
• O tools/list funciona sem chave, permitindo que você explore todos os schemas antes mesmo de criar uma conta. As chamadas de ferramenta são limitadas a 20 por minuto por chave.

• Os preços são fornecidos em tempo real pelo list_models — a mesma fonte que o site utiliza.
• Toda chamada de vídeo (e lote de várias imagens) primeiro retorna uma estimativa sem cobrar nada; o agente repete a chamada enviando confirm_cost para iniciar.
• Cada resultado inclui cost_charged_usd e balance_remaining_usd.
• Falhas de provedores parceiros e rejeições por filtro de conteúdo são reembolsadas automaticamente — a mesma política do aplicativo web.
• O uso opcional de idempotency_key garante que novas tentativas de rede nunca cobrem em duplicidade.

• As URLs dos resultados são assinadas e válidas por 24 horas; a mídia em si permanece na sua conta — chame get_result novamente para obter novos links ou faça o download diretamente pelo site.
• As chaves de API são armazenadas como hash e exibidas apenas uma vez na criação; revogue-as a qualquer momento em seu perfil.
• Conexões OAuth usam tokens de acesso de uma hora com refresh rotativo, guardados como hash e válidos só para este servidor; desconectar um app no perfil invalida os tokens na hora.
• O log de uso de cada chave (ferramenta, modelo, custo, pré-visualização do prompt) fica visível em Perfil → Chaves de API MCP.
• As gerações via MCP aparecem no mesmo histórico de geração e análise que as gerações feitas pelo site.

x402 é um protocolo aberto que permite a um agente pagar uma única requisição com stablecoin. É um endpoint separado do servidor MCP: POST /api/x402. Não é preciso conta, chave de API nem recarga.

1. Envie o nome da ferramenta e os argumentos. O servidor responde 402 com o preço exato dessa chamada.
2. Assine o pagamento em USDC na rede Base e repita a requisição com o cabeçalho X-PAYMENT.
3. Imagens e fala chegam na mesma resposta. O vídeo devolve um job_id; consulte gratuitamente GET /api/x402/result/{jobId}.

Ferramentas disponíveis: generate_image, generate_speech, generate_video. Os preços são os mesmos do estúdio web e do MCP; a chamada custa o que custa a geração, sem recarga mínima.

Se um vídeo pago falhar, o pagador recebe um token de crédito no mesmo valor, válido por 90 dias. Envie-o como refund_token em uma chamada posterior. Os pagamentos não são reembolsados on-chain. O catálogo legível por máquina com os preços atuais está em GET /api/x402.