nano-banana-mcp

nano-banana-mcp

Um servidor Model Context Protocol para geração e edição de imagens com IA usando os modelos de imagem Gemini "Nano Banana" do Google, via Interactions API.

Gere, edite e itere em imagens diretamente do Claude Code, Claude Desktop, Cursor ou qualquer cliente compatível com MCP — com edição multitorre, grounding por busca, storyboards intercalados, conjuntos de ícones com estilo consistente e imagem a partir de vídeo.

Tudo gerado por este servidor — um produto fotorealista, uma ilustração isométrica com texto legível e um adesivo vetorial. Sem edições.

Observação: Este servidor usa a Interactions API do Gemini, que está atualmente em beta. Os modelos de imagem Gemini 3 (gemini-3-pro-image, gemini-3.1-flash-image) podem exigir acesso na sua chave de API. O nível nano (gemini-2.5-flash-image) é o mais amplamente disponível. Consulte Requisitos.

Recursos

• Texto para imagem — imagens de alta qualidade a partir de um prompt, até 4K, com controle de proporção e resolução
• Edição multitorre — itere de forma conversacional; cada resultado retorna um interaction_id que você passa de volta para continuar editando
• Imagens de referência — até 14 entradas para provador virtual, colocação de produto, composição, transferência de estilo, restauração de fotos, substituição de atributos, maquetes 2D→3D
• Grounding por busca — ancore imagens em dados em tempo real (clima, notícias, placares) com o Google Search e o Google Image Search
• Histórias intercaladas — um prompt → uma sequência de imagens legendadas (storyboards, quadrinhos, receitas, explicadores ilustrados)
• Conjuntos de ícones com estilo consistente — geração encadeada mantém uma aparência uniforme em um conjunto de ícones
• Imagem a partir de vídeo — gere miniaturas/pôsteres a partir de uma URL pública do YouTube
• Pré-visualizações inline — pré-visualizações reduzidas retornadas ao cliente para que o modelo veja o que gerou e se autocorrija
• Robusto — novas tentativas automáticas com backoff em limites de taxa e erros transitórios; mensagens de erro claras e acionáveis

Início Rápido

1. Obtenha uma chave de API do Gemini

Crie uma chave em Google AI Studio.

2. Instalação

git clone https://github.com/petrkindlmann/nano-banana-mcp.git
cd nano-banana-mcp
npm install

3. Registre com seu cliente MCP

Claude Code

claude mcp add nano-banana --scope user \
  --env GEMINI_API_KEY=your_key_here \
  -- node /absolute/path/to/nano-banana-mcp/index.js

Claude Desktop / Cursor / Windsurf / VS Code

Adicione à sua configuração MCP (ex.: ~/Library/Application Support/Claude/claude_desktop_config.json no macOS):

{
  "mcpServers": {
    "nano-banana": {
      "command": "node",
      "args": ["/absolute/path/to/nano-banana-mcp/index.js"],
      "env": {
        "GEMINI_API_KEY": "your_key_here"
      }
    }
  }
}

Reinicie seu cliente. As cinco ferramentas abaixo aparecerão.

Configuração

Variável de ambiente	Obrigatória	Descrição
GEMINI_API_KEY	✅	Sua chave da API Gemini.
NANO_BANANA_MODEL_NANO	—	Substitui o ID do modelo do nível nano.
NANO_BANANA_MODEL_FLASH	—	Substitui o ID do modelo do nível flash.
NANO_BANANA_MODEL_PRO	—	Substitui o ID do modelo do nível pro.

Os IDs de modelo são modelos beta/pré-visualização que o Google rotaciona e ocasionalmente descontinua. Se uma versão mais recente for lançada — ou um ID configurado for descontinuado — aponte um nível para um novo modelo sem editar o código:

"env": {
  "GEMINI_API_KEY": "your_key_here",
  "NANO_BANANA_MODEL_FLASH": "gemini-3.2-flash-image"
}

Cada nível mantém seu perfil de capacidade (tamanhos, proporções, grounding) independentemente do ID que você atribuir a ele.

Uso

Basta pedir em linguagem natural — seu cliente MCP escolhe a ferramenta e os argumentos corretos.

Você: Gere uma imagem hero 16:9 de uma floresta de pinheiros enevoada ao amanhecer, cinematográfica, salve em hero.jpg

Claude: chama generate_image → salva hero.jpg, retorna um interaction_id e uma pré-visualização

Você: Deixe o nevoeiro mais denso e adicione um veado na clareira

Claude: chama edit_image com o interaction_id anterior → hero-v2.jpg

A edição multitorre é a forma recomendada de iterar: cada resultado carrega um interaction_id, e passá-lo de volta mantém todo o contexto da conversa para que as edições permaneçam consistentes.

Ferramentas

Ferramenta	Descrição
generate_image	Gera uma única imagem a partir de um prompt de texto. Grounding opcional por busca, pensamento e controle de proporção/tamanho.
edit_image	Edita ou itera em uma imagem — encadeie via previous_interaction_id, ou passe imagens de referência do disco.
generate_story	Gera texto + imagens intercalados a partir de um prompt (storyboards, quadrinhos, receitas, explicadores).
generate_icon_set	Gera um conjunto de ícones com estilo consistente via geração encadeada.
generate_from_video	Gera uma imagem a partir de uma URL pública de vídeo do YouTube (apenas modelo flash).

Modelos

Nível	ID do modelo	Tamanhos	Grounding por busca	Pensamento	Entrada de vídeo	Saída JPEG
nano	gemini-2.5-flash-image	1K	—	—	—	— (apenas PNG)
flash	gemini-3.1-flash-image	0.5K, 1K, 2K, 4K	web + imagem	—	✅	✅
pro	gemini-3-pro-image	1K, 2K, 4K	web	✅	—	✅

Qual devo usar?

• flash (padrão) — sua opção preferida. Melhor equilíbrio geral entre qualidade, custo e latência. Até 4K, grounding por busca, as proporções mais amplas (21:9, 1:4, etc.), e o único nível que aceita entrada de vídeo.
• pro — o renderizador de maior qualidade. Use para ativos profissionais/entregáveis, instruções complexas com múltiplos elementos e texto legível renderizado dentro da imagem (infográficos, pôsteres, cardápios). Uma passada de "Thinking" integrada refina a composição antes de renderizar. Mais lento e mais caro.
• nano — velocidade e volume. Apenas 1K, sem grounding/pensamento, sempre retorna PNG. Use quando precisar gerar muitas imagens rapidamente e a qualidade por imagem importar menos.

generate_story usa como padrão pro (melhor qualidade intercalada); generate_from_video é bloqueado em flash (o único nível que aceita vídeo).

generate_image

Argumento	Tipo	Padrão	Observações
prompt	string	—	Obrigatório. O que gerar.
output	string	—	Obrigatório. Caminho do arquivo de saída. A extensão define o formato: .png (padrão) ou .jpg (apenas flash/pro — nano sempre retorna PNG).
model	nano/flash/pro	flash	Nível do modelo.
ratio	string	1:1	Ex.: 16:9, 9:16, 4:3; 21:9/1:4/4:1/1:8/8:1 são exclusivos do flash.
size	0.5K/1K/2K/4K	1K	0.5K é exclusivo do flash.
use_search	boolean	false	Ancora com o Google Search (flash/pro).
use_image_search	boolean	false	Também usa o Google Image Search como contexto visual (flash).
show_thinking	boolean	false	Inclui os resumos de pensamento do modelo (pro).
preview	boolean	true	Retorna uma pequena imagem de pré-visualização ao cliente.

Retorna o caminho do arquivo e um interaction_id — passe-o para edit_image para continuar iterando.

edit_image

Mesmos controles de imagem de generate_image, mais:

Argumento	Tipo	Observações
previous_interaction_id	string	Continue uma geração/edição anterior de forma conversacional (a forma recomendada de iterar).
reference_images	string[]	Caminhos para imagens de referência no disco (máx. 14; flash: 10 objetos + 4 personagens, pro: 6 + 5).

generate_story

Argumento	Tipo	Padrão	Observações
prompt	string	—	Obrigatório. Ex.: "Um storyboard de 6 painéis de uma raposa aprendendo a voar, ilustrações intercaladas com legendas."
output_dir	string	—	Obrigatório. Diretório para as imagens numeradas.
basename	string	story	Prefixo do nome do arquivo.
model	nano/flash/pro	pro	pro oferece a melhor qualidade intercalada.
ratio / size	string	—	Opcional; omita para deixar o modelo decidir.

generate_icon_set

Argumento	Tipo	Padrão	Observações
prompts	string[]	—	Obrigatório. Um prompt por ícone.
output_dir	string	—	Obrigatório. Os arquivos são nomeados após cada prompt (icon-shopping-cart.png).
model	nano/flash/pro	flash
size	0.5K/1K/2K/4K	1K

generate_from_video

Argumento	Tipo	Padrão	Observações
youtube_url	string	—	Obrigatório. URL pública do YouTube.
prompt	string	—	Obrigatório. O que gerar a partir do vídeo.
output	string	—	Obrigatório. Caminho do arquivo de saída.
ratio	string	16:9
size	0.5K/1K/2K/4K	1K
preview	boolean	true

Dicas de prompt

Para obter os melhores resultados, escreva frases completas descrevendo sujeito + cenário + iluminação + câmera/lente + clima — batidas narrativas em vez de sopa de palavras-chave.

Um retrato em close-up fotorrealista de um ceramista japonês idoso com rugas profundas e um sorriso caloroso. Luz suave de hora dourada entrando pela janela. Capturado com lente de retrato 85mm, fundo com bokeh suave. Clima sereno e magistral.

Requisitos

• Node.js 18+ (usa o executor node:test integrado e módulos ES modernos)
• Uma chave de API Gemini (GEMINI_API_KEY)
• A Interactions API está em beta; os níveis de imagem Gemini 3 (flash, pro) podem exigir acesso. O nível nano é o mais amplamente disponível — defina model: "nano" se flash/pro não estiverem disponíveis na sua chave.

Desenvolvimento

npm test          # unit tests (node:test) — no API key needed
npm run smoke     # live smoke test — requires GEMINI_API_KEY

O código é dividido em módulos focados:

• lib/config.js — tabelas de modelos, validação de proporção/tamanho, auxiliares
• lib/gemini.js — cliente de API, novas tentativas, extração de resposta, pré-visualizações
• lib/tools.js — esquemas e manipuladores de ferramentas
• index.js — integração do servidor MCP

Licença

MIT