npm package: @justmpm/nanobanana
Description: MCP Server for AI image generation using Google Gemini 3.1 Flash Image (NanoBanana)
Author: Koda AI Studio
Latest version: 0.2.0

# @justmpm/nanobanana

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

## Descrição

Este servidor MCP (Model Context Protocol) permite gerar, editar e fazer inpainting de imagens usando o modelo Gemini 3.1 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

```bash
npm install -g @justmpm/nanobanana
```

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

```bash
npx @justmpm/nanobanana
```

## Configuração

### Variável de Ambiente Obrigatória

Este MCP requer uma API key do Google AI Studio:

```bash
export GEMINI_API_KEY=sua-api-key-aqui
```

### Como obter a API Key

1. Acesse [Google AI Studio](https://aistudio.google.com/)
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):**
```json
{
  "mcpServers": {
    "nanobanana": {
      "command": "npx",
      "args": ["@justmpm/nanobanana"],
      "env": {
        "GEMINI_API_KEY": "sua-api-key-aqui"
      }
    }
  }
}
```

**Opção 2 - Caminho absoluto (desenvolvimento local):**
```json
{
  "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:

```json
{
  "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:**
```json
{
  "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:**
```json
{
  "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:**
```json
{
  "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

```json
{
  "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

```json
{
  "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

```json
{
  "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

```bash
# 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