MCP Nanobanana

🚀 納米香蕉 - MCP圖像生成擴展

納米香蕉是一款專業的MCP（模型上下文協議）擴展，適用於任何支持MCP的客戶端（包括Gemini CLI和Codex CLI），可用於生成和處理圖像。它默認使用google/gemini-2.5-flash-image模型，並預先配置為連接到OpenRouter。你可以通過調整MODEL_*環境變量，將其指向任何託管該模型的提供商。

✨ 主要特性

• 🎨 文本到圖像生成：根據描述性提示創建令人驚歎的圖像。
• ✏️ 圖像編輯：使用自然語言指令修改現有圖像。
• 🔧 圖像修復：恢復和增強老舊或受損的照片。
• 📁 智能文件管理：用戶友好的文件名，自動防止重複。

📋 前提條件

1. 安裝並配置支持MCP的CLI（例如Gemini CLI、Codex CLI）。
2. Node.js 18+ 和 npm。
3. API密鑰：你需要從OpenRouter或其他託管google/gemini-2.5-flash-image模型的提供商處獲取API密鑰。

默認情況下，擴展會與OpenRouter進行通信。當你需要使用其他託管該模型的提供商時，可使用以下可選覆蓋配置：

• MODEL_BASE_URL – 替代提供商的端點（默認值：https://openrouter.ai/api/v1）
• MODEL_ID – 覆蓋模型ID（默認值：google/gemini-2.5-flash-image）
• MODEL_REFERER / MODEL_TITLE – 某些提供商需要的分析頭信息
• MODEL_GENERATE_PATH – 替代生成端點路徑（默認值：/responses）

如果你使用的是OpenRouter，請參考他們的身份驗證指南來生成API密鑰。對於其他提供商，請查閱他們的文檔。

🚀 快速開始

📦 安裝指南

從NPM安裝（推薦）

對於大多數用戶來說，通過npx或CLI的擴展管理器進行安裝是最簡單的方法。

Gemini CLI： 安裝擴展時，系統會提示你輸入API密鑰。

gemini extensions install https://github.com/Aeven-AI/mcp-nanobanana

Codex CLI：

codex mcp add nanobanana --env MODEL_API_KEY="YOUR_API_KEY_HERE" -- npx -y @aeven/nanobanana-mcp@latest

Opencode CLI：

1. 運行opencode config edit（或手動打開opencode.jsonc設置文件）。
2. 使用類似以下的條目註冊服務器：

{
    "mcp": {
        "nanobanana": {
            "type": "local",
            "command": ["npx", "-y", "@aeven/nanobanana-mcp@latest"],
            "enabled": true,
            "environment": {
                "MODEL_API_KEY": "{env:MODEL_API_KEY}"
            }
        }
    }
}

3. 保存文件並重啟Opencode，使其加載新的MCP服務器。

Claude Code：

1. 打開Claude Code，導航到Settings → Model Context Protocol → Add Server。
2. 將命令設置為npx，參數設置為-y和@aeven/nanobanana-mcp@latest。
3. 添加一個環境變量MODEL_API_KEY，指向你的提供商密鑰。
4. 保存服務器配置並重啟Claude Code（或重新加載窗口）以進行連接。

本地開發安裝

如果你已經克隆了這個倉庫以進行代碼開發，可以註冊本地版本。 1. 安裝服務器依賴（每次克隆後執行一次）：

npm run install-deps

2. 構建服務器：

npm run build

3. 在CLI中註冊： Codex CLI：

codex mcp add nanobanana --env MODEL_API_KEY="YOUR_API_KEY_HERE" -- node mcp-server/dist/index.js

🔑 API密鑰配置

此擴展需要MODEL_API_KEY才能與模型提供商（如OpenRouter）進行身份驗證。以下是為不同客戶端配置API密鑰的方法：

Gemini CLI

安裝過程中系統會自動提示你輸入API密鑰。

Codex CLI

codex mcp add命令有一個專門的--env標誌來處理此問題。“安裝”部分提供的命令已經包含了該標誌，這是推薦的安裝方式。

其他CLIs（Shell配置文件）

對於其他客戶端，或者如果你更喜歡手動管理密鑰，可以在shell的配置文件（例如~/.zshrc、~/.bashrc或~/.profile）中設置MODEL_API_KEY環境變量。

1. 在文件末尾添加以下行：

export MODEL_API_KEY="YOUR_API_KEY_HERE"

2. 重啟終端使更改生效。

激活

重啟你的MCP CLI（如Gemini CLI、Codex CLI等）。以下命令將可用：

• /generate - 單張或多張圖像生成，支持風格/變體選項
• /edit - 圖像編輯
• /restore - 圖像修復
• /icon - 生成多種尺寸的應用圖標、網站圖標和UI元素
• /pattern - 生成用於背景的無縫圖案和紋理
• /story - 生成講述視覺故事或展示流程的系列圖像
• /diagram - 生成專業的技術圖表、流程圖和架構模型
• /nanobanana - 自然語言接口

💻 使用示例

🎯 特定命令（推薦）

生成圖像

# 單張圖像
/generate "a watercolor painting of a fox in a snowy forest"

# 多張變體並預覽
/generate "sunset over mountains" --count=3 --preview

編輯圖像

/edit my_photo.png "add sunglasses to the person"
/edit portrait.jpg "change background to a beach scene" --preview

修復圖像

/restore old_family_photo.jpg "remove scratches and improve clarity"

生成圖標

/icon "coffee cup logo" --sizes="64,128,256" --type="app-icon" --preview

創建圖案

/pattern "geometric triangles" --type="seamless" --style="geometric" --preview

生成故事圖像

/story "a seed growing into a tree" --steps=4 --type="process" --preview

創建圖表

/diagram "user login process" --type="flowchart" --style="professional" --preview

🌟 自然語言命令（靈活）

/nanobanana create a logo for my tech startup
/nanobanana I need 5 different versions of a cat illustration in various art styles
/nanobanana fix the lighting in sunset.jpg and make it more vibrant

🎨 高級生成選項

/generate命令支持高級選項，可用於創建具有不同風格和參數的多個變體。

生成選項

• --count=N - 變體數量（1 - 8，默認值：1）
• --styles="style1,style2" - 以逗號分隔的藝術風格
• --variations="var1,var2" - 特定的變體類型
• --format=grid|separate - 輸出格式（默認值：separate）
• --seed=123 - 用於可重複變體的種子
• --preview - 自動在默認查看器中打開生成的圖像

可用風格

• photorealistic - 照片級質量的圖像
• watercolor - 水彩畫風格
• oil-painting - 油畫技法
• sketch - 手繪草圖風格
• pixel-art - 復古像素藝術風格
• anime - 動漫/漫畫藝術風格
• vintage - 復古美學
• modern - 現代風格
• abstract - 抽象藝術風格
• minimalist - 簡潔、簡約的設計

可用變體

• lighting - 不同的光照條件（戲劇性、柔和）
• angle - 不同的視角（俯視、特寫）
• color-palette - 不同的配色方案（暖色調、冷色調）
• composition - 不同的佈局（居中、三分法）
• mood - 不同的情感基調（歡快、戲劇性）
• season - 不同的季節（春季、冬季）
• time-of-day - 不同的時間（日出、日落）

高級示例

風格變體

/generate "mountain landscape" --styles="watercolor,oil-painting,sketch,photorealistic"
# 以4種不同的藝術風格創建相同的山脈場景

多個變體

/generate "cozy coffee shop" --variations="lighting,mood" --count=4
# 生成：戲劇性光照、柔和光照、歡快氛圍、戲劇性氛圍的版本

🎯 圖標生成

/icon命令專門用於創建具有適當尺寸和格式的應用圖標、網站圖標和UI元素。

圖標選項

• --sizes="16,32,64" - 圖標的像素尺寸數組（常見值：16、32、64、128、256、512、1024）
• --type="app-icon|favicon|ui-element" - 圖標類型（默認值：app-icon）
• --style="flat|skeuomorphic|minimal|modern" - 視覺風格（默認值：modern）
• --format="png|jpeg" - 輸出格式（默認值：png）
• --background="transparent|white|black|color" - 背景類型（默認值：transparent）
• --corners="rounded|sharp" - 應用圖標的邊角風格（默認值：rounded）

圖標示例

# 完整的應用圖標集
/icon "productivity app with checklist" --sizes="64,128,256,512" --corners="rounded"

# 網站圖標包
/icon "mountain logo" --type="favicon" --sizes="16,32,64" --format="png"

🎨 圖案和紋理生成

/pattern命令用於創建適合作為背景和設計元素的無縫圖案和紋理。

圖案選項

• --size="256x256" - 圖案瓷磚的尺寸（常見值：128x128、256x256、512x512）
• --type="seamless|texture|wallpaper" - 圖案類型（默認值：seamless）
• --style="geometric|organic|abstract|floral|tech" - 圖案風格（默認值：abstract）
• --density="sparse|medium|dense" - 元素密度（默認值：medium）
• --colors="mono|duotone|colorful" - 配色方案（默認值：colorful）
• --repeat="tile|mirror" - 無縫圖案的平鋪方法（默認值：tile）

圖案示例

# 網站背景圖案
/pattern "subtle geometric hexagons" --type="seamless" --colors="duotone" --density="sparse"

# 材質紋理
/pattern "brushed metal surface" --type="texture" --style="tech" --colors="mono"

📖 視覺敘事

/story命令用於生成講述視覺故事或展示逐步過程的系列圖像。

故事選項

• --steps=N - 系列圖像的數量（2 - 8，默認值：4）
• --type="story|process|tutorial|timeline" - 序列類型（默認值：story）
• --style="consistent|evolving" - 各幀之間的視覺一致性（默認值：consistent）
• --layout="separate|grid|comic" - 輸出佈局（默認值：separate）
• --transition="smooth|dramatic|fade" - 步驟之間的過渡風格（默認值：smooth）
• --format="storyboard|individual" - 輸出格式（默認值：individual）

故事示例

# 產品開發過程
/story "idea to launched product" --steps=5 --type="process" --style="consistent"

# 教育教程
/story "git workflow tutorial" --steps=6 --type="tutorial" --layout="comic"

📊 技術圖表

/diagram命令用於根據簡單的文本描述生成專業的技術圖表、流程圖和架構模型。

圖表選項

• --type="flowchart|architecture|network|database|wireframe|mindmap|sequence" - 圖表類型（默認值：flowchart）
• --style="professional|clean|hand-drawn|technical" - 視覺風格（默認值：professional）
• --layout="horizontal|vertical|hierarchical|circular" - 佈局方向（默認值：hierarchical）
• --complexity="simple|detailed|comprehensive" - 詳細程度（默認值：detailed）
• --colors="mono|accent|categorical" - 配色方案（默認值：accent）
• --annotations="minimal|detailed" - 標籤和註釋級別（默認值：detailed）

圖表類型和用例

• flowchart：流程、決策樹、工作流
• architecture：系統架構、微服務、基礎設施
• network：網絡拓撲、服務器配置
• database：數據庫模式、實體關係
• wireframe：UI/UX原型、頁面佈局
• mindmap：概念圖、想法層次結構
• sequence：序列圖、API交互

圖表示例

# 開發工作流
/diagram "CI/CD pipeline with testing stages" --type="flowchart" --complexity="detailed"

# 系統設計
/diagram "chat application architecture" --type="architecture" --style="technical"

📁 文件管理

智能文件名生成

圖像會根據你的提示以用戶友好的名稱保存：

• "sunset over mountains" → sunset_over_mountains.png
• "abstract art piece" → abstract_art_piece.png

自動防止重複

如果文件已經存在，會自動添加計數器：

• sunset_over_mountains.png
• sunset_over_mountains_1.png
• sunset_over_mountains_2.png

文件搜索位置

在進行編輯/修復時，擴展會在以下位置搜索輸入圖像：

1. 當前工作目錄
2. ./images/ 子目錄
3. ./input/ 子目錄
4. ./nanobanana-output/ 子目錄
5. ~/Downloads/
6. ~/Desktop/

輸出目錄

生成的圖像會自動保存到./nanobanana-output/目錄。

🛠️ 開發

構建命令

# 構建MCP服務器
npm run build

# 安裝MCP服務器依賴
npm run install-deps

# 開發模式，監聽文件變化
npm run dev

MCP服務器命令

# 直接構建MCP服務器
cd mcp-server && npm run build

# 獨立啟動服務器（用於測試）
cd mcp-server && npm start

# 開發模式，監聽TypeScript文件變化
cd mcp-server && npm run dev

測試

# 運行完整套件（構建 + 單元測試 + 集成測試）
cd mcp-server && npm test

# 僅運行單元測試（FileHandler、ImageGenerator使用模擬fetch）
cd mcp-server && npm run test:unit

# 僅運行集成測試（使用內存中的MCP握手和存根圖像生成器）
cd mcp-server && npm run test:integration

默認的集成測試使用內存傳輸和存根圖像生成器，因此可以離線運行，無需API密鑰。

要端到端地測試真實的OpenRouter工作流，請在設置MODEL_API_KEY後運行手動腳本：

cd mcp-server
MODEL_API_KEY="sk-..." node ./tests/manual/openrouter.integration.js

生成的資產會放在mcp-server/nanobanana-output/目錄下，以便手動檢查。

驗證npm打包

運行自動冒煙測試，確保發佈的npm二進制文件能正確啟動：

npm run verify:npm

此命令會打包項目，在臨時目錄中安裝tarball，啟動npx nanobanana-mcp，並確認stdio服務器橫幅出現。在成功消息出現後可以安全中斷。

🔧 技術細節

關鍵組件

• index.ts：使用@modelcontextprotocol/sdk的MCP服務器，用於專業的協議處理。
• imageGenerator.ts：處理所有OpenRouter API交互和響應處理。
• fileHandler.ts：管理文件I/O、智能文件名生成和文件搜索。
• types.ts：共享的TypeScript接口，確保類型安全。

MCP服務器協議

該擴展使用官方的模型上下文協議（MCP）SDK進行強大的客戶端 - 服務器通信：

• 協議：通過stdio的JSON-RPC
• SDK：@modelcontextprotocol/sdk
• 工具：generate_image、edit_image、restore_image

API集成

• 模型：google/gemini-2.5-flash-image（可通過環境變量配置）
• 傳輸：直接HTTP請求（默認使用OpenRouter；設置MODEL_BASE_URL可指向其他託管該模型的提供商）
• 響應處理：Base64解碼，對缺少的圖像數據進行優雅降級處理
• 輸出尺寸：所有圖像均以1024×1024分辨率返回（模型最大分辨率）

錯誤處理

• 全面的錯誤消息，包含調試信息
• 對API響應解析進行優雅降級處理
• 文件驗證和搜索路徑報告

🐛 故障排除

常見問題

1. “命令未識別”：驗證MCP服務器是否已為你的CLI註冊（例如，Gemini CLI的~/.gemini/extensions/nanobanana-extension/，Codex用戶的Codex CLI配置），並重啟客戶端。
2. “未找到API密鑰”：確保在安裝時提示輸入API密鑰時已正確輸入，或者如果你不使用Gemini CLI，確保MODEL_API_KEY環境變量已正確設置。
3. “構建失敗”：確保已安裝Node.js 18+，並運行npm run install-deps && npm run build。
4. “未找到圖像”：檢查輸入文件是否在上述搜索目錄之一中。
5. npx安裝錯誤：~/.npm/_npx中的陳舊目錄可能導致安裝失敗。使用rm -rf ~/.npm/_npx/*刪除緩存，然後重新運行安裝命令。

調試模式

MCP服務器包含詳細的調試日誌，會顯示在你的CLI控制檯（如Gemini CLI、Codex CLI等）中，以幫助診斷問題。

📄 許可證

• 許可證：Apache License 2.0
• 安全：安全策略

🤝 貢獻

1. 分叉倉庫。
2. 創建功能分支。
3. 在模塊化架構中進行更改。
4. 運行npm run build確保編譯通過。
5. 使用你的MCP CLI（如Gemini CLI、Codex CLI等）進行測試。
6. 提交拉取請求。