Big Banana MCP

Server MCP in TypeScript per usare i modelli Google Nano Banana tramite Gemini API, con supporto per:

• generazione da testo
• editing da una o piu immagini di riferimento
• fusione di piu immagini
• immagini locali passate come file path, oltre a base64/data URL e URI del Files API
• grounding opzionale con Google Search
• controlli su aspect ratio, risoluzione e thinking

Il server salva la configurazione in un file nascosto nella home utente:

• ~/.bigbananamcp.json

Se la chiave API non e configurata, i tool MCP falliscono in modo esplicito e indicano l'endpoint HTTP locale da usare per configurarla.

Requisiti

• Node.js 20+
• una Google API key valida per Gemini API

Installazione

npm install
npm run build

Avvio

Per uso MCP via stdio:

npm run start

Oppure direttamente da git via npx, utile per configurazioni MCP come quella di VS Code:

npx --yes git+https://git.enne2.net/enne2/big-banana-mcp.git

Per sviluppo:

npm run dev

Il server avvia anche un endpoint HTTP locale di configurazione, di default su http://127.0.0.1:3210.

Endpoint di configurazione

GET /health

Ritorna lo stato del servizio.

GET /config

Ritorna la configurazione corrente senza esporre la chiave completa.

PUT /config

Aggiorna il file ~/.bigbananamcp.json.

Esempio:

curl -X PUT http://127.0.0.1:3210/config \
  -H 'Content-Type: application/json' \
  -d '{
    "apiKey": "YOUR_GOOGLE_API_KEY",
    "defaultModel": "gemini-3.1-flash-image-preview",
    "defaultAspectRatio": "16:9",
    "defaultImageSize": "2K",
    "defaultThinkingLevel": "dynamic",
    "enableGoogleSearchByDefault": false
  }'

POST /config/validate

Controlla se la configurazione contiene una chiave API presente e formalmente valida.

Tool MCP esposti

nano_banana_generate

Tool principale per generazione, editing e multimodalita.

Supporta:

• solo prompt testo
• prompt + immagine esistente da filePath, fileUri o base64
• prompt + immagini multiple per fusion/context preservation
• grounding opzionale con Google Search
• salvataggio opzionale dei risultati su disco

Esempio con file locale esistente:

{
  "prompt": "Mantieni il logo originale, aggiungi la sigla BBMCP nella targhetta inferiore.",
  "inputImages": [
    {
      "filePath": "/home/enne2/dev/bigbananamcp/generated/big-banana-logo-1.png",
      "inputMethod": "auto"
    }
  ],
  "outputDirectory": "/home/enne2/dev/bigbananamcp/generated",
  "outputPrefix": "big-banana-logo-edit"
}

Esempio con piu immagini da fondere:

{
  "prompt": "Combina queste reference in un unico badge vettoriale pulito, mantenendo la banana centrale.",
  "inputImages": [
    {
      "filePath": "/abs/path/reference-1.png"
    },
    {
      "fileUri": "https://example.com/reference-2.png",
      "mimeType": "image/png"
    }
  ]
}

nano_banana_models

Elenca modelli consigliati e relative capacita operative.

nano_banana_config_status

Ritorna stato configurazione, path del file nascosto e URL del servizio HTTP locale.

Note progettuali

• Il modello predefinito e gemini-3.1-flash-image-preview, cioe Nano Banana 2.
• Sono supportati anche gemini-2.5-flash-image e gemini-3-pro-image-preview.
• Per immagini locali il server usa inlineData per file piccoli e il Gemini Files API per file grandi o riutilizzabili.
• Gli input fileUri permettono di riusare file gia caricati nel Files API o URI pubblici/signed quando supportati dal modello.
• Tutti i log runtime vanno su stderr per non interferire con il trasporto stdio MCP.

Debug in VS Code

Il file .vscode/mcp.json e gia pronto. Dopo npm run build, VS Code puo avviare e debuggare questo server MCP usando node dist/index.js.