MCP Nanobanana

🚀 ナノバナナ - MCP画像生成拡張機能

この拡張機能は、MCP（Model Context Protocol）互換のクライアント（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キーの設定

この拡張機能は、モデルプロバイダー（例：OpenRouter）との認証にMODEL_API_KEYが必要です。以下は、異なるクライアントでの設定方法です。

Gemini CLI

インストールプロセス中に自動的にAPIキーの入力を求められます。

Codex CLI

codex mcp addコマンドには、これを処理するための専用の--envフラグがあります。「インストール」セクションで提供されているコマンドにはすでにこれが含まれており、推奨されるインストール方法です。

その他のCLI（シェルプロファイル）

他のクライアントの場合、または手動でキーを管理したい場合は、シェルのプロファイルファイル（例：~/.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 - 自然言語インターフェース

💻 使用例

基本的な使用法

この拡張機能は、さまざまなユースケースに対応する複数のコマンドオプションを提供します。

⚠️ 重要提示 以下の例ではGemini CLIのスラッシュコマンドを使用しています。Codex CLIや他のMCPクライアントでは、クライアントが提供する構文を使用して同じMCPツール（generate_image、edit_imageなど）を呼び出します。

🎯 特定のコマンド（推奨）

画像生成:

# 単一画像
/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コマンドは、さまざまなスタイルとパラメーターで複数のバリエーションを作成するための高度なオプションをサポートしています。

高度な使用例

スタイルバリエーション:

/generate "mountain landscape" --styles="watercolor,oil-painting,sketch,photorealistic"
# 同じ山の風景を4つの異なるアートスタイルで作成

複数のバリエーション:

/generate "cozy coffee shop" --variations="lighting,mood" --count=4
# 生成されるもの: 劇的な照明、柔らかい照明、明るい雰囲気、劇的な雰囲気のバージョン

アイコン生成

/iconコマンドは、適切なサイズと形式でアプリアイコン、ファビコン、およびUI要素を作成することに特化しています。

アイコンの使用例

# 完全なアプリアイコンセット
/icon "productivity app with checklist" --sizes="64,128,256,512" --corners="rounded"

# ウェブサイトのファビコンパッケージ
/icon "mountain logo" --type="favicon" --sizes="16,32,64" --format="png"

パターンとテクスチャ生成

/patternコマンドは、背景やデザイン要素に最適なシームレスなパターンとテクスチャを作成します。

パターンの使用例

# ウェブサイトの背景パターン
/pattern "subtle geometric hexagons" --type="seamless" --colors="duotone" --density="sparse"

# 素材テクスチャ
/pattern "brushed metal surface" --type="texture" --style="tech" --colors="mono"

ビジュアルストーリーテリング

/storyコマンドは、視覚的な物語を語るか、段階的なプロセスを示す連続画像を生成します。

ストーリーの使用例

# 製品開発プロセス
/story "idea to launched product" --steps=5 --type="process" --style="consistent"

# 教育的なチュートリアル
/story "git workflow tutorial" --steps=6 --type="tutorial" --layout="comic"

技術図

/diagramコマンドは、シンプルなテキスト説明からプロフェッショナルな技術図、フローチャート、およびアーキテクチャモックアップを生成します。

ダイアグラムのタイプとユースケース

• 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、モックされたfetchを使用したImageGenerator）
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: ファイルの入出力、スマートなファイル名生成、およびファイル検索を管理
• types.ts: 型安全のための共有TypeScriptインターフェース

MCPサーバープロトコル

この拡張機能は、堅牢なクライアント - サーバー通信のために公式のModel Context Protocol (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. "Command not recognized": MCPサーバーがCLIに登録されていることを確認し（例：Gemini CLIの場合は~/.gemini/extensions/nanobanana-extension/、Codex CLIの場合はCodex CLIの設定）、クライアントを再起動します。
2. "No API key found": インストール時にAPIキーを正しく入力したことを確認するか、Gemini CLIを使用していない場合はMODEL_API_KEY環境変数が正しく設定されていることを確認します。
3. "Build failed": Node.js 18+がインストールされていることを確認し、npm run install-deps && npm run buildを実行します。
4. "Image not found": 入力ファイルが検索対象のディレクトリのいずれかにあることを確認してください（上記の「ファイル検索場所」を参照）。
5. npx install errors: ~/.npm/_npxの古いディレクトリがインストール失敗の原因になることがあります。rm -rf ~/.npm/_npx/*でキャッシュを削除し、インストールコマンドを再実行します。

デバッグモード

MCPサーバーには、問題の診断に役立つ詳細なデバッグログがCLIコンソール（Gemini CLI、Codex CLIなど）に表示されます。

📄 ライセンス

• ライセンス: Apache License 2.0
• セキュリティ: Security Policy

🤝 コントリビューション

1. リポジトリをフォークします。
2. 機能ブランチを作成します。
3. モジュール化されたアーキテクチャで変更を加えます。
4. npm run buildを実行してコンパイルが正常に行われることを確認します。
5. MCP CLI（Gemini CLI、Codex CLIなど）でテストします。
6. プルリクエストを送信します。