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
• 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

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 base
• prompt + immagini multiple
• grounding opzionale con Google Search
• salvataggio opzionale dei risultati su disco

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.
• Le immagini vengono inviate come inlineData in base64, in linea con l'SDK ufficiale @google/genai.
• 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.