Nano Banana MCP no Cursor e no Codex: configuração e exemplos

Digitar um prompt numa aba de chat, baixar um PNG e arrastá-lo para o seu repositório é um ciclo lento quando o código já está no Cursor ou no Codex. Um servidor MCP elimina esse desvio: o agente de programação chama o próprio Nano Banana, salva o arquivo onde o seu projeto pode usá-lo e continua editando a mesma imagem ao longo das interações. Este artigo conecta o Nano Banana MCP no Cursor e no Codex desde uma configuração vazia até uma chamada de imagem funcionando, com os arquivos exatos, os prompts que se comportam bem e os erros que aparecem logo no primeiro dia. As configurações do Cursor e do Codex seguem a documentação atual de cada um, e os detalhes do servidor vêm do README público do pacote. Quando um detalhe depende do servidor que você escolher, o texto informa isso.

O que o servidor realmente faz

MCP (Model Context Protocol) é um padrão para um cliente de IA chamar ferramentas externas. Um servidor de imagens expõe algumas delas, como generate_image ou edit_image, e o modelo dentro do Cursor ou do Codex decide quando chamar uma delas com base no que você pede no chat. O Nano Banana é o apelido do modelo de imagem Gemini, do Google, disponível como Nano Banana no PicassoIA, com o Nano Banana Pro como o nível de maior resolução. O próprio servidor MCP é um pequeno processo Node na sua máquina. Ele guarda o seu token do Gemini, encaminha o prompt ao Google e grava o resultado no disco.

Veja o que um servidor típico do Nano Banana oferece ao seu agente:

• Texto para imagem: descreva uma cena e receba um PNG de volta.
• Editar por caminho de arquivo: aponte uma imagem existente e descreva a mudança.
• Continuar editando: refine a última imagem sem repetir o prompt inteiro.
• Ferramentas de status: informam se o token está configurado antes que você desperdice uma chamada.

Por que vale a pena rodar isso dentro do editor? Porque o mesmo chat que escreve o seu componente principal também pode produzir a imagem principal, nomear o arquivo e atualizar a tag <img>. O prompt fica no histórico do chat, ao lado do commit, e cada iteração custa uma frase em vez de uma ida e volta ao navegador.

💡 O servidor roda localmente e consome a sua cota do Gemini. Nem o Cursor nem o Codex cobram você pelas chamadas de imagem.

Requisitos e verificação de confiança

Cinco minutos de preparação evitam a maioria das falhas descritas mais adiante neste artigo.

A lista de verificação

Execute node --version primeiro. Se ele mostrar qualquer versão abaixo de 18, atualize antes de mexer em qualquer arquivo de configuração, porque um runtime antigo demais gera erros que parecem não ter relação com o problema.

Escolha um servidor em que você confie

Vários pacotes npm usam o nome Nano Banana. nano-banana-mcp documenta seis ferramentas: generate_image, edit_image, continue_editing, get_last_image_info, configure_gemini_token e get_configuration_status. @saroby/nanobanana-mcp lista apenas duas, generate_image e list_images. @mindstone/mcp-server-nano-banana é uma terceira opção. Os nomes das ferramentas variam entre eles, então prompts escritos para um nem sempre vão funcionar com outro.

Um servidor npx executa código no seu computador com as suas permissões de usuário e enxerga o token que você lhe der. Leia o repositório, verifique a data da última versão e fixe uma versão exata depois que tudo funcionar. Este passo a passo usa nano-banana-mcp porque a lista de ferramentas dele é documentada publicamente.

Configure o Nano Banana MCP no Cursor

O Cursor lê servidores MCP de dois lugares: .cursor/mcp.json dentro de um projeto, e ~/.cursor/mcp.json na sua pasta pessoal, para servidores que você quer em todos os lugares. Quando os dois definem o mesmo nome de servidor, o arquivo do projeto prevalece.

Escreva o arquivo mcp.json

Crie .cursor/mcp.json na raiz do seu projeto:

{
  "mcpServers": {
    "nano-banana": {
      "command": "npx",
      "args": ["-y", "nano-banana-mcp"],
      "env": {
        "GEMINI_API_KEY": "${env:GEMINI_API_KEY}"
      }
    }
  }
}

Copiar prompt

Depois siga estes passos:

1. Salve o arquivo. O Cursor o detecta sem precisar de uma reinstalação completa.
2. Abra o painel Customize na barra lateral e encontre nano-banana na lista de MCP.
3. Ative a chave. Servidores desativados não carregam e não aparecem no chat.
4. Pergunte ao agente: "Verifique o status da configuração do Nano Banana." Um servidor em verde e uma resposta clara de status indicam que a conexão funciona.

Por padrão, o Cursor pede aprovação antes de cada ferramenta MCP ser executada. Clique na seta ao lado do nome da ferramenta para inspecionar os argumentos. Vale a pena fazer isso nas primeiras chamadas, para ver exatamente qual prompt o agente escreveu.

💡 No Windows, se o servidor não iniciar, substitua o comando por cmd e os argumentos por ["/c", "npx", "-y", "nano-banana-mcp"]. Algumas configurações não conseguem executar npx diretamente.

Mantenha os segredos fora do Git

A sintaxe ${env:GEMINI_API_KEY} diz ao Cursor para ler o valor do seu ambiente quando ele iniciar o servidor. Assim, o arquivo em si não guarda nenhum segredo e pode ser versionado com segurança. O Cursor resolve várias variáveis dessa forma: ${env:NAME}, ${userHome} e ${workspaceFolder} são as que você mais vai usar.

Defina a variável uma vez, onde o Cursor consiga vê-la:

• macOS e Linux: exporte-a no perfil do seu shell e depois inicie o Cursor a partir de um terminal novo. Um aplicativo aberto pelo dock pode não enxergar variáveis definidas apenas em um arquivo de shell.
• Windows: adicione-a como variável de ambiente do usuário e depois feche e reabra o Cursor.

Configure o Nano Banana MCP no Codex

O Codex guarda tudo em um único arquivo TOML, ~/.codex/config.toml, e oferece um comando para editá-lo, então você raramente precisa abrir o arquivo.

Registre pelo CLI

Execute isto uma vez em um terminal:

codex mcp add nano-banana --env GEMINI_API_KEY=your-token-here -- npx -y nano-banana-mcp

Copiar prompt

Tudo depois do duplo hífen é o comando que inicia o servidor. Confirme a entrada com codex mcp list, depois inicie uma sessão do Codex e digite /mcp para ver os servidores ativos e o status de cada um. Os outros subcomandos são login para servidores OAuth e remove para excluir uma entrada.

A desvantagem: essa forma grava o seu token em config.toml como texto simples. Para um notebook pessoal, isso pode ser aceitável. Para qualquer coisa compartilhada, use o método seguinte.

Edite o config.toml manualmente

O mesmo servidor, com o token herdado do seu shell em vez de armazenado:

[mcp_servers.nano-banana]
command = "npx"
args = ["-y", "nano-banana-mcp"]
env_vars = ["GEMINI_API_KEY"]
startup_timeout_sec = 60
tool_timeout_sec = 120

Copiar prompt

Três campos importam aqui:

• env_vars lista os nomes de variáveis que o Codex copia do processo pai, então o token nunca chega ao arquivo.
• startup_timeout_sec importa na primeira execução, quando npx baixa o pacote antes que o servidor consiga responder. Se a primeira execução der timeout, aumente esse valor.
• tool_timeout_sec limita uma única chamada de ferramenta. A geração de imagens demora mais do que a maioria das ferramentas, então dê a ela esse espaço.

Cursor e Codex lado a lado

A diferença prática está no compartilhamento. Um .cursor/mcp.json no nível do projeto pode ser versionado, então a equipe inteira recebe a mesma definição de servidor e só precisa do próprio token. O Codex mantém a lista na sua pasta pessoal, o que combina com uma configuração individual, mas precisa de uma linha curta no README se os colegas quiserem copiá-la.

Prompts que vale copiar

Um servidor funcionando é só metade do trabalho. O prompt decide se você recebe um recurso utilizável ou um palpite às cegas. Três hábitos ajudam nos dois clientes: nomeie o arquivo que você quer, peça uma imagem por chamada e descreva a fotografia, não o clima.

Imagem principal para uma landing page

Cole isto no chat:

Use a ferramenta generate_image do Nano Banana para criar uma imagem principal 16:9 para a página de preços: um notebook fino sobre uma mesa de carvalho desgastada, com luz quente de manhã vinda de uma janela à esquerda, uma caneca de cerâmica em primeiro plano, profundidade de campo rasa, sem texto, sem logotipos. Depois mova o arquivo para public/images/ como pricing-hero.png e atualize a tag de imagem em Hero.tsx.

A maioria dos servidores salva na própria pasta padrão, como nano-banana-images na sua pasta Documentos no Windows, ou generated_imgs no diretório de trabalho no macOS e no Linux. Por isso o prompt pede ao agente que mova o arquivo. Os agentes fazem essa movimentação com um comando comum de terminal.

Fotos de produto e edições

Gere primeiro uma imagem base e depois edite-a no lugar:

Gere uma foto de estúdio de um tênis de couro branco sobre um bloco de concreto claro, contra um fundo cinza contínuo, com luz de softbox vinda do alto à esquerda. Salve como shoe.png.

Depois faça uma alteração pontual:

Use edit_image em shoe.png: troque o fundo para areia quente, mantenha exatamente como estão as costuras, os cadarços e a sola.

Se o seu servidor tiver uma ferramenta continue_editing, pequenos ajustes viram uma única frase: "Deixe a sombra mais suave." Alguns servidores também aceitam várias imagens de referência em uma chamada, o que ajuda quando você precisa de um estilo consistente em um conjunto de fotos de produto. Confira o README do seu servidor antes de depender disso.

Prompts escritos pelo modelo

Você não precisa escrever todos os prompts sozinho. Peça ao agente que leia uma página e proponha três prompts de imagem que combinem com o texto, depois aprove um deles. O modelo que comanda o Cursor ou o Codex faz isso bem, porque consegue ver o componente ao redor, as cores da marca na sua folha de estilos e a proporção do espaço reservado.

Se quiser uma segunda opinião fora do editor, o PicassoIA hospeda modelos de linguagem que você pode usar para a mesma tarefa, incluindo o Claude Sonnet 5 e o GPT 5.6 Sol. Cole o texto da sua página, peça prompts no formato de prompt fraco e prompt melhor, como acima e leve o vencedor de volta ao agente.

Como corrigir erros comuns

A maioria das falhas cai em três grupos: o servidor nunca inicia, o token está ausente ou os arquivos acabam em um lugar inesperado.

O servidor nunca inicia

Execute o comando exato da sua configuração em um terminal comum. Se ele mostrar um erro ali, o problema está no servidor ou no seu ambiente, e não no Cursor ou no Codex.

Erros de token e cota

Um erro de autenticação quase sempre significa que a variável está ausente no processo que inicia o servidor, mesmo que ela exista no seu shell. Exiba-a no mesmo terminal de onde você inicia o cliente. Se você usar uma ferramenta de status como get_configuration_status, chame-a primeiro e leia a resposta antes de culpar o modelo.

Respostas de cota ou de limite de taxa vêm do Google, não do MCP. Desacelere, peça uma imagem por vez e confira seu uso no Google AI Studio. Tentar de novo em um ciclo sem pausa só faz a limitação durar mais.

Rode o Nano Banana no PicassoIA

Nem toda imagem precisa de um servidor local. Quando você quer testar um prompt rapidamente, compartilhar um resultado ou evitar gerenciar um token, o caminho pelo navegador é mais rápido.

Use o modelo no navegador

Como usar o Nano Banana no PicassoIA:

1. Abra a página do modelo e digite o seu prompt. Use o mesmo vocabulário fotográfico que você daria ao agente MCP.
2. Escolha a proporção que combina com o seu espaço. 16:9 serve para banners principais, 1:1 serve para grades de produtos.
3. Gere, revise e refine o prompt em vez de gerar de novo às cegas. Mude uma coisa de cada vez.
4. Baixe o resultado e coloque-o no seu projeto, ou guarde-o como referência para o agente.

Dois modelos irmãos valem a pena quando o primeiro resultado está perto, mas não é o ideal. O Nano Banana 2 é a geração mais nova, e o Nano Banana 2 Lite troca um pouco de qualidade por velocidade, o que combina com rascunhos. O Nano Banana Pro é a escolha para recursos finais que precisam de mais resolução.

Transforme imagens fixas em vídeo

Uma imagem fixa do seu fluxo de trabalho no editor pode virar um clipe curto. Pegue a imagem principal, abra um modelo de imagem para vídeo e descreva o movimento: uma aproximação lenta, vapor saindo de uma caneca, luz deslizando por uma parede. O Seedance 2.0 gera vídeo com áudio integrado, o Seedance 2.5 Lite produz clipes de até 10 segundos, e o Veo 3.1 é outra opção quando você quer o modelo de vídeo do Google ao lado do modelo de imagem do Google.

Chame o PicassoIA a partir de código

O PicassoIA também tem uma API para desenvolvedores e um conector MCP. A API fica em https://api.picassoia.com/v1 e usa um token Bearer que começa com pia_sk_. Ela segue um fluxo no estilo Replicate: crie uma previsão com POST /v1/models/{owner}/{name}/predictions, consulte GET /v1/predictions/{id} e depois leia o resultado. Os limites incluem 5 previsões simultâneas por conta e 4.000 caracteres por prompt.

Uma ressalva honesta: os modelos expostos pela API e pelo conector MCP são picassoia/picassoia-image, picassoia/picassoia-image-editor-pro, picassoia/picassoia-video e picassoia/seedance-2.5-lite. O Nano Banana não está nessa lista curta, então use a página do navegador para ele. Você ainda pode consultar as páginas do PicassoIA Image Editor Pro e do PicassoIA Image para ver o que cada um faz. O acesso à API depende do seu plano, e o texto das páginas de preços e de API não é o mesmo, então confirme o seu plano antes de construir algo sobre ele.

Experimente no seu próprio projeto

Agora você tem o ciclo completo: um servidor que inicia, um token que fica fora do git, prompts que nomeiam arquivos e câmeras e correções para as falhas que param a maioria das pessoas logo no primeiro passo. Escolha um espaço real do seu projeto atual, um banner principal ou um cartão de produto, e rode a configuração do Cursor ou do Codex descrita acima hoje mesmo.

Se quiser ver o que o modelo faz antes de mexer em qualquer arquivo de configuração, abra-o no PicassoIA, cole um dos prompts deste artigo e compare o resultado com o que o seu agente produz. Experimente primeiro o Nano Banana e depois explore os outros modelos de imagem e vídeo em picassoia.com/en/all-models. Teste a iluminação, a lente e a proporção, e guarde os prompts que funcionam em um arquivo ao lado do seu código.