@justmpm/nanobanana

MCP Server para geração de imagens usando Google Gemini 2.5 Flash Image.

Descrição

Este servidor MCP (Model Context Protocol) permite gerar, editar e fazer inpainting de imagens usando o modelo Gemini 2.5 Flash Image da Google. NanoBanana é o codinome para este modelo de geração de imagens de alta qualidade.

Por que usar?

• Geração de imagens de texto: Crie imagens a partir de descrições textuais
• Edição inteligente: Modifique imagens existentes usando prompts em linguagem natural
• Inpainting preciso: Edite regiões específicas usando máscaras
• Integração MCP: Funciona com Claude Desktop, OpenCode e outros clientes MCP
• Fácil configuração: Basta uma API key do Google AI Studio

Instalação

npm install -g @justmpm/nanobanana

Ou use diretamente via npx (sem instalação):

npx @justmpm/nanobanana

Configuração

Variável de Ambiente Obrigatória

Este MCP requer uma API key do Google AI Studio:

export GEMINI_API_KEY=sua-api-key-aqui

Como obter a API Key

1. Acesse Google AI Studio
2. Faça login com sua conta Google
3. Clique em "Get API Key" ou "Create API Key"
4. Copie a chave gerada

Uso

Configuração no Claude Desktop

Adicione ao seu arquivo claude_desktop_config.json:

Opção 1 - Via npx (recomendado):

{
  "mcpServers": {
    "nanobanana": {
      "command": "npx",
      "args": ["@justmpm/nanobanana"],
      "env": {
        "GEMINI_API_KEY": "sua-api-key-aqui"
      }
    }
  }
}

Opção 2 - Caminho absoluto (desenvolvimento local):

{
  "mcpServers": {
    "nanobanana": {
      "command": "node",
      "args": ["D:\\caminho\\para\\nanobanana\\dist\\index.js"],
      "env": {
        "GEMINI_API_KEY": "sua-api-key-aqui"
      }
    }
  }
}

Configuração no OpenCode

Adicione ao seu arquivo de configuração do OpenCode:

{
  "mcpServers": {
    "nanobanana": {
      "command": "npx",
      "args": ["@justmpm/nanobanana"],
      "env": {
        "GEMINI_API_KEY": "sua-api-key-aqui"
      }
    }
  }
}

Tools Disponíveis

nano_generate - Gera imagem de texto

Gera uma imagem a partir de uma descrição textual.

Parâmetros: | Parâmetro | Tipo | Obrigatório | Descrição | |-----------|------|-------------|-----------| | prompt | string | Sim | Descrição textual da imagem (ex: "um carro vermelho em uma estrada ensolarada") | | outputPath | string | Sim | Caminho completo para salvar a imagem (ex: "public/images/carro.png") |

Exemplo:

{
  "prompt": "um gato laranja dormindo em uma rede na praia ao pôr do sol, estilo arte digital",
  "outputPath": "public/images/gato-praia.png"
}

Retorno:

✅ Imagem gerada com sucesso!
📍 Salva em: public/images/gato-praia.png
📏 Tamanho: 245.67 KB
🎨 Formato: image/png

nano_edit - Edita imagem existente

Edita uma imagem existente usando instruções textuais. Permite modificar cores, adicionar/remover elementos, mudar estilos, etc.

Parâmetros: | Parâmetro | Tipo | Obrigatório | Descrição | |-----------|------|-------------|-----------| | imagePath | string | Sim | Caminho para a imagem de origem | | prompt | string | Sim | Instrução de edição (ex: "mude a cor do carro para vermelho") | | outputPath | string | Sim | Caminho para salvar a imagem editada |

Exemplo:

{
  "imagePath": "public/images/foto.png",
  "prompt": "adicione um chapéu vermelho na pessoa",
  "outputPath": "public/images/foto-com-chapeu.png"
}

Retorno:

✅ Imagem editada com sucesso!
📍 Origem: public/images/foto.png
📍 Salva em: public/images/foto-com-chapeu.png
📏 Tamanho: 198.34 KB
🎨 Formato: image/png

nano_inpaint - Inpainting com máscara

Edita uma região específica da imagem usando uma máscara. Na máscara: branco = região a editar, preto = região a preservar.

Parâmetros: | Parâmetro | Tipo | Obrigatório | Descrição | |-----------|------|-------------|-----------| | imagePath | string | Sim | Caminho para a imagem original | | maskPath | string | Sim | Caminho para a máscara (mesmas dimensões da imagem) | | prompt | string | Sim | O que gerar na região mascarada | | outputPath | string | Sim | Caminho para salvar o resultado |

Exemplo:

{
  "imagePath": "public/images/cenario.png",
  "maskPath": "public/images/mascara.png",
  "prompt": "um carro azul esportivo",
  "outputPath": "public/images/cenario-com-carro.png"
}

Retorno:

✅ Inpainting concluído com sucesso!
📍 Imagem: public/images/cenario.png
🎭 Máscara: public/images/mascara.png
📍 Salvo em: public/images/cenario-com-carro.png
📏 Tamanho: 312.45 KB
🎨 Formato: image/png

Formatos Suportados

O NanoBanana suporta os seguintes formatos de imagem:

| Formato | MIME Type | Extensão | |---------|-----------|----------| | PNG | image/png | .png | | JPEG | image/jpeg | .jpg, .jpeg | | GIF | image/gif | .gif | | WebP | image/webp | .webp |

Exemplos de Uso

Exemplo 1: Gerar imagem para blog

{
  "prompt": "ilustração minimalista de uma pessoa programando em um laptop, cores frias, estilo flat design",
  "outputPath": "blog/posts/hero-image.png"
}

Exemplo 2: Editar foto de perfil

{
  "imagePath": "profile/original.jpg",
  "prompt": "mude o fundo para um jardim florido com luz natural",
  "outputPath": "profile/edited.jpg"
}

Exemplo 3: Remover objeto com inpainting

1. Crie uma máscara onde o objeto a remover está em branco
2. Use o prompt para preencher com o conteúdo desejado

{
  "imagePath": "photos/beach.png",
  "maskPath": "masks/person-mask.png",
  "prompt": "areia branca da praia com pegadas",
  "outputPath": "photos/beach-clean.png"
}

Estrutura do Projeto

nanobanana/
├── src/
│   ├── index.ts        # Servidor MCP principal
│   ├── client.ts       # Cliente Gemini
│   ├── types.ts        # Tipos TypeScript
│   └── tools/
│       ├── index.ts    # Barrel export
│       ├── generate.ts # Tool nano_generate
│       ├── edit.ts     # Tool nano_edit
│       └── inpaint.ts  # Tool nano_inpaint
├── dist/               # Build compilado
├── package.json
├── tsconfig.json
├── README.md           # Este arquivo
├── CLAUDE.md           # Documentação para IAs
└── AGENTS.md           # Guia para subagents

Desenvolvimento

# Clonar repositório
git clone https://github.com/justmpm/nanobanana-mcp

# Instalar dependências
npm install

# Build
npm run build

# Desenvolvimento com watch
npm run dev

# Executar
GEMINI_API_KEY=sua-key npm start

Documentação Adicional

CLAUDE.md

Documentação técnica para IAs sobre como o MCP funciona internamente. Inclui:

• Arquitetura do sistema
• Fluxo de dados
• Padrões de código
• Como estender com novas tools

Para IAs: Leia CLAUDE.md para entender a arquitetura e implementação.

AGENTS.md

Guia simplificado para subagents sobre como usar as tools. Inclui:

• Referência rápida das tools
• Exemplos de uso
• Dicas de troubleshooting

Para Subagents: Consulte AGENTS.md para orientações rápidas.

Limitações Conhecidas

• Tamanho da imagem: Imagens muito grandes podem falhar
• Rate limits: Sujeito aos limites da API do Gemini
• Qualidade da máscara: Para inpainting, máscaras mal definidas podem gerar resultados imprecisos

Troubleshooting

Erro: "GEMINI_API_KEY não definida"

Certifique-se de configurar a variável de ambiente antes de iniciar o servidor.

Erro: "No image data returned from Gemini"

O modelo pode ter retornado apenas texto. Tente reformular o prompt para ser mais específico sobre a imagem desejada.

Imagem não aparece no caminho especificado

Verifique se o diretório de destino existe e tem permissões de escrita.

Licença

MIT © Koda AI Studio

Links

• Koda AI Studio: https://kodaai.app
• Google AI Studio: https://aistudio.google.com/
• Model Context Protocol: https://modelcontextprotocol.io/
• Repositório: https://github.com/justmpm/nanobanana-mcp