Gerar imagens no Gemini CLI: configuração de servidor MCP

O Gemini CLI é o agente de terminal de código aberto do Google, e o MCP é o protocolo usado para acessar ferramentas externas. Conecte-o a um servidor MCP remoto e a mesma sessão de chat que edita seu código também poderá gerar imagens, vídeos e áudio, salvando os arquivos diretamente no seu diretório de trabalho.

Resposta rápida: execute gemini mcp add --transport http --scope user bananabanana https://bananabanana.pro/api/mcp -H "Authorization: Bearer $BB_KEY", confirme a confiança na pasta quando a CLI solicitar e verifique gemini mcp list para encontrar o status verde Connected. As imagens custam a partir de $0.03 por unidade, debitadas por geração do seu saldo.

Uma janela de terminal em uma mesa com pequenas imagens emolduradas saindo dela, ilustração editorial

Tudo o que está descrito abaixo foi testado no Gemini CLI 0.55.1 em 17 de agosto de 2026, com uma chave bb_live_… ativa. Onde a documentação oficial difere do comportamento real da CLI, nós apontamos claramente.

Configuração direta

Apenas dois comandos. O primeiro registra o servidor:

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"

O segundo verifica o status:

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

Se você receber Disabled em vez de Connected, leia a seção seguinte antes de alterar qualquer outra coisa. Esse detalhe me custou bons cinco minutos.

Cinco detalhes que a documentação não menciona

A confiança da pasta desativa tudo silenciosamente. Execute gemini mcp list em um diretório não confiável para a CLI e você verá isto:

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

Observe a segunda linha: até mesmo um servidor com --scope user permanece inativo. A CLI solicita confirmação na primeira execução interativa; se você estiver usando scripts, a decisão de confiança fica em ~/.gemini/trustedFolders.json como um mapeamento simples do caminho para TRUST_FOLDER. É uma decisão sensata, mas um modo de falha confuso, pois nada na palavra "Disabled" indica que o problema é a pasta.

gemini mcp add grava url, e não httpUrl. A documentação descreve httpUrl para Streamable HTTP. O que a CLI 0.55.1 gerou na prática foi:

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

Ambos os formatos conectam. Mas ao comparar uma configuração da documentação com o que a CLI produziu, você pode pensar que uma delas está com erro. Ambas funcionam.

O escopo padrão é project, e é para lá que sua chave vai. Se omitir --scope user, a chave será salva em .gemini/settings.json dentro do seu repositório. Um simples git add . depois e ela estará no histórico. Use sempre --scope user ou mantenha o cabeçalho como referência de variável de ambiente, como no bloco acima.

A interpolação de $BB_KEY funciona, mas falha em silêncio. Com a variável exportada, você vê Connected. Ao abrir um novo terminal sem exportá-la, a mesma configuração mostra Disconnected em vez de indicar falha de autenticação. Vale adicionar a linha ao seu perfil de shell.

O Gemini CLI sonda SSE e recebe 405. Ao analisar os logs do servidor durante a conexão, a sequência foi: POST initialize (200), POST notification (202), GET /api/mcp (405), POST tools/list (200). A requisição GET é uma tentativa da CLI de abrir um canal de Server-Sent Events em um servidor stateless. Ela falha com 405, a CLI prossegue normalmente e tudo funciona. Se você roda seu próprio servidor MCP, não perca tempo com esse 405.

Uma parede de pequenas portas trancadas com uma única entreaberta e iluminada, ilustração editorial

O que você obtém e quanto custa

Nove ferramentas ficam disponíveis na sessão, o mesmo conjunto listado na referência de ferramentas. Quatro são gratuitas para chamada: list_models, get_account, get_result, list_generations. As restantes são cobradas por geração do saldo da sua conta.

Serviço	Modelo	Preço
Imagem, 1K	Nano Banana 2 Lite	$0.03
Imagem, 512 → 4K	Nano Banana 2	$0.03 – $0.13
Imagem, 1K → 4K	Nano Banana Pro	$0.11 – $0.20
Vídeo, 3–10 s com som	Gemini Omni Flash	$0.10 por segundo
Vídeo, 4–8 s	Família Veo 3.1	até $4.40 por clipe
Voz	Gemini Flash TTS	$0.01 a cada 200 caracteres

Chamadas de vídeo e lotes de imagens sempre solicitam cotação prévia. O agente recebe o preço exato, nada é debitado antecipadamente e a geração só inicia após a confirmação desse valor. Rejeições de filtros de moderação e falhas upstream são reembolsadas automaticamente, algo essencial ao executar lotes de prompts em segundo plano.

As recargas oferecem bônus: 5% a partir de $50, 10% a partir de $100, e um código promocional ativo adiciona mais 10% do depósito. Um depósito de $100 com cupom credita $120.

Moedas ao lado de uma pilha de pequenas imagens emolduradas e uma tira de filme organizadas como escada, ilustração editorial

Por que gerar imagens Nano Banana no Gemini faz sentido?

Dois caminhos para o mesmo portão brilhante, um curto e direto, o outro sinuoso passando por postos de controle, ilustração editorial

O Gemini CLI se comunicando com um modelo de imagem Gemini por meio de um servidor terceiro pode parecer um desvio. Há um caminho direto: configurar uma conta de faturamento no Google Cloud, provisionar as APIs de modelos, configurar credenciais e gerenciar cotas por região. É uma boa alternativa se seu trabalho for gerenciar infraestrutura.

Nosso modelo resolve outra questão. Um único token, saldo pré-pago, sem contas de faturamento de nuvem, sem tickets de cota ou amarração regional. Você também acessa os modelos de vídeo Veo e Omni e geração de voz pela mesma conexão, cobrados por geração e não por projeto. Se o seu foco é produzir em vez de administrar plataformas, essa é a escolha mais prática.

Em escala massiva, a infraestrutura direta em nuvem pode sair mais barata. Mas nossa opção permite começar em minutos e impede que você deixe custos rodando sem perceber.

Se você usa outros editores, o mesmo servidor se integra com Claude Code, Cursor e Codex usando a mesma chave API e o arquivo de configuração apropriado.

Caso de uso prático: ilustrações para documentação

Um caso de uso real e eficiente: um repositório com uma pasta docs/, doze páginas, cada uma precisando de uma imagem de cabeçalho em um estilo visual padronizado.

Prompt na sessão:

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.

O agente lê os arquivos, chama generate_image para cada página, aguarda via get_result, baixa os arquivos e insere a sintaxe markdown. Doze imagens a $0.11 totalizam $1.32, e tudo roda em segundo plano enquanto você toma um café. Todas as ilustrações deste artigo vieram desse mesmo fluxo no Nano Banana Pro com uma descrição de estilo compartilhada.

Duas dicas antes de tentar: gere primeiro uma imagem de teste para validar o estilo (um prompt incorreto repetido em doze arquivos desperdiça $1.32) e mantenha o --trust desligado, pois a confirmação a cada ferramenta paga evita loops acidentais do agente.

Uma dúzia de pequenos cartões ilustrados organizados em grade sobre uma mesa compartilhando um estilo visual, ilustração editorial

É possível usar OAuth em vez de uma chave API?

O Gemini CLI documenta suporte a OAuth 2.0 para servidores MCP remotos, com descoberta automática e o comando /mcp auth. Nosso servidor é um servidor de autorização OAuth 2.1 completo (registro dinâmico de clientes, PKCE S256, descoberta RFC 9728), e clientes como Claude Code e claude.ai autenticam dessa forma sem precisar inserir chaves manualmente.

O fluxo com chave de API foi testado de ponta a ponta e funciona de maneira sólida. O fluxo OAuth via Gemini CLI não foi validado nesta sessão, portanto trate-o como funcional em teoria, mas não confirmado. Gerar uma chave de API leva dez segundos e ela não expira até você revogá-la.

Perguntas frequentes

Onde fica o arquivo de configurações?

Em ~/.gemini/settings.json para o escopo de usuário, ou .gemini/settings.json para o escopo de projeto. O comando gemini mcp add --scope user grava no primeiro.

Por que o servidor aparece como Disabled?

A pasta não é confiável para a CLI. Confirme a confiança no terminal ao iniciar ou adicione o caminho em ~/.gemini/trustedFolders.json com o valor TRUST_FOLDER. Servidores de escopo de usuário também são desativados em pastas não confiáveis.

Posso restringir as ferramentas que o modelo enxerga?

Sim. Use --include-tools e --exclude-tools no gemini mcp add, ou os campos includeTools / excludeTools nas configurações. Exclusões têm prioridade sobre inclusões, o que é ótimo para liberar imagens e bloquear vídeo.

Funciona em um repositório compartilhado com o time?

Configure o servidor no escopo do projeto e a chave em uma variável de ambiente, nunca no arquivo. Cada desenvolvedor executa export BB_KEY=… com sua própria chave e o repositório fica limpo.

O que acontece se uma geração falhar?

Você recebe um reembolso automático, inclusive em casos de bloqueio pelo filtro de conteúdo. Se o prompt estiver no limite das diretrizes, vale a pena tentar novamente: a checagem de segurança analisa os pixels finais e uma nova execução desenha uma imagem diferente.

Prefere interface gráfica? O gerador web roda os mesmos modelos com o mesmo saldo. No terminal, comece chamando list_models após conectar: é grátis, lista os preços atuais e confirma que tudo está funcionando antes de gastar seus primeiros centavos.