Labnana MCP

labnana-mcp

Labnana OpenAPI 用の MCP サーバーです。Claude、Claude Code、その他の MCP クライアントから、Labnana を使って画像を生成・編集できます。

現在の OpenAPI モデル（製品名と model パラメーターの対応）：

製品名	model	プロバイダー	解像度	最適な用途
Nano Banana Pro	gemini-3-pro-image	Google	1K / 2K / 4K	画像内のテキスト、キャラクターの一貫性、高忠実度の出力
Nano Banana 2	gemini-3.1-flash-image	Google	1K / 2K / 4K	素早い反復と極端なアスペクト比
GPT-Image-2	gpt-image-2	OpenAI	1K / 2K / 4K	仕様に基づく生成、レイアウト制御、イラスト
GPT-Image-2.5 Flare	gpt-image-2.5-flare	OpenAI	1K / 2K / 4K	より高速な生成
GPT-Image-2.5 Sunburst	gpt-image-2.5-sunburst	OpenAI	1K / 2K / 4K	ディテールの密度が高い画像
Wan2.7 Image Pro	wan2.7-image-pro	Alibaba	1K / 2K / 4K¹	写実的な画像やポスター風の画像
Wan2.7 Image	wan2.7-image	Alibaba	1K / 2K	低コストの日常的な生成
Seedream 5.0 Pro	seedream-5-0-pro	ByteDance	1K / 2K	座標指定による領域編集と中国語の指示

¹ wan2.7-image-pro はテキストから画像への生成でのみ 4K に対応し、参照画像を使った生成は 2K に制限されます。OpenAPI リファレンスには GPT-Image-2.5 Flare と Sunburst が記載されています。モデルディレクトリには 1K / 2K / 4K と 10 種類のアスペクト比が記載されていますが、統合ガイドのモデル一覧にはまだこれらのバリエーションが追加されていません。どちらのバリエーションも最大 4 枚の参照画像に対応し、料金は同じです。生成前に estimate_credits で現在の料金を確認してください。

GitHub · npm · MCP Registry · Glama · 中文文档

インストール

Node.js 20.9 以降が必要です。

Claude Code

1. Labnana API Keys コンソールで API キーを作成します。
2. Claude Code が使用する環境で LABNANA_API_KEY を利用できるようにします。
3. サーバーを追加します。

claude mcp add labnana -- npx -y @exoticknight/labnana-mcp

パッケージは次のコマンドで直接起動することもできます。

npx -y @exoticknight/labnana-mcp

DeepSeek Harness（DSH）

DSH の公式 MCP クライアントプラグインからサーバーを追加します。initialize が返すバージョンで、この MCP Apps 対応ビルドを識別したい場合は、2.2.0 を固定してください。

- id: mcp-labnana
  name: '@deepseek-ai/dsh-mcp-client'
  config:
    serverName: labnana
    transport: stdio
    command: npx
    args: ['-y', '@exoticknight/[email protected]']
    env:
      LABNANA_API_KEY: !!js process.env.LABNANA_API_KEY

DSH の MCP ブリッジは、対応する ImageContent を呼び出し元のビジョンモデルに渡せます。バージョン 2.1 では、generate_image と get_generation_task 用の標準 MCP Apps シングルファイル View も公開されます。MCP Apps 対応の DSH Web ホストではプレビューがインライン表示されます。一方、標準の汎用 DSH ツールカードでは、モデルが画像を受け取っていても JSON にフォールバックする場合があります。これはクライアントの表示上の制限であり、生成結果が失われたわけではありません。

ローカルのソースチェックアウトを使用する場合は、同じ行で command: node を指定し、args に dist/index.js の絶対パスを指定して、cwd をこのリポジトリに設定します。現在の標準 DSH ビルドは MCP ツールをブリッジしますが、汎用ツールカードでは MCP リソースを利用しません。MCP Apps ホストがない場合も、モデルのビジョン機能は動作し、カードは JSON にフォールバックします。

Cursor と VS Code

ワンクリックでインストールできます（インストール後にプレースホルダーの API キーを置き換えてください）。

Claude Desktop とその他の MCP クライアント

同等の mcpServers 設定を使用します。

{
  "mcpServers": {
    "labnana": {
      "command": "npx",
      "args": ["-y", "@exoticknight/labnana-mcp"],
      "env": {
        "LABNANA_API_KEY": "lh_xxxxxxxxx"
      }
    }
  }
}

ローカルのソースチェックアウト

npm install
npm run build

次に、生成された dist/index.js を使ってサーバーを設定します。

claude mcp add labnana -- node <path-to-repo>/dist/index.js

Windows では、次のような絶対パスを使用します。

claude mcp add labnana -- node C:/path/to/labnana-mcp/dist/index.js

設定

サーバーは次の環境変数を読み込みます。

変数	必須	説明
LABNANA_API_KEY	はい	Labnana API キーです。
LABNANA_OUTPUT_DIR	いいえ	画像の保存先のデフォルトディレクトリです。作業ディレクトリ内の labnana-images/ にフォールバックします。

次のコマンドラインオプションもサポートされています。

オプション	説明
--api-key <key>	ローカルプロセス用の API キーを指定します。
--base-url <url>	デフォルトの API エンドポイント https://api.labnana.com を上書きします。
--output-dir <dir>	画像の保存先のデフォルトディレクトリです。

コマンドライン引数はローカルのプロセス一覧に表示される場合があるため、環境変数の使用を推奨します。

ツール

ツール	説明
generate_image	テキストから画像への生成、画像から画像への生成、画像編集を一括で行います。元画像を保存し、サイズ上限付きの MCP 画像プレビュー、構造化メタデータ、デフォルトで JSON フォールバックを返します。4K のリクエストは内部でポーリングします。
estimate_credits	画像を生成せずに、生成に必要なクレジット数を見積もります。
get_subscription	サブスクリプションのステータス、クレジット残高、無料利用に関する情報を取得します。
list_generation_tasks	ページネーションと任意のステータスフィルターを指定して、生成タスクの履歴を一覧表示します。
get_generation_task	タスクの詳細と公開画像 URL を取得します（generate_image がタイムアウトした場合に便利です）。

使用方法

画像を生成する

{
  "name": "generate_image",
  "arguments": {
    "model": "gemini-3-pro-image",
    "prompt": "Change the background of the image to the grasslands of Inner Mongolia",
    "referenceImages": [
      {
        "fileData": {
          "fileUri": "https://cdn.labnana.com/xxx.png",
          "mimeType": "image/png"
        }
      }
    ],
    "imageConfig": {
      "imageSize": "2K",
      "aspectRatio": "16:9"
    }
  }
}

デフォルトは outputMode=hybrid です。元画像全体をディスクに保存する一方で、上限サイズ内の MCP 画像プレビュー、structuredContent、および同等の JSON テキストをまとめて返します。これにより、Codex、Claude Code、Claude Desktop、その他の MCP クライアントとの段階的な互換性を実現できます。保存先ディレクトリを指定するには saveDir を使用します。

1K、2K、4K、および get_generation_task の結果はすべて、同じエンベロープを使用します。

{
  "schemaVersion": 1,
  "status": "succeeded",
  "taskId": "task-123",
  "images": [
    {
      "index": 0,
      "mimeType": "image/png",
      "width": 4096,
      "height": 4096,
      "byteLength": 18442231,
      "sha256": "...",
      "url": "https://.../original.png",
      "filePath": "C:\\...\\labnana.png",
      "preview": { "included": true, "mimeType": "image/jpeg", "width": 1600, "height": 1600 }
    }
  ]
}

画像の base64 は標準の MCP ImageContent にのみ含まれ、テキストや構造化メタデータには重複して含まれません。4K の元画像全体はインライン化されません。プレビューの最大辺は 1600 ピクセル、目標のサイズ上限は 2 MiB で、元画像の場所は filePath／url で確認できます。

画像から画像を生成する場合や画像を編集する場合は、referenceImages を使用します。fileData.fileUri は gs:// と https:// に対応しています。小さい画像は inlineData.data を通じて base64 として渡すことができます。

4K リクエストは自動的に非同期タスクとして実行されます。サーバーがタスクを作成し、レート制限に応じて待機間隔を調整しながらポーリングを行い、元画像をダウンロードして保存し、プレビューを作成します。待機時間が timeoutSeconds（デフォルトは 300）を超えた場合、結果は status=pending と taskId を返しますが、これは生成失敗として扱われません。後から get_generation_task を使用して、最終プレビューと元画像の URL を取得してください。

クレジットの見積もり

{
  "name": "estimate_credits",
  "arguments": {
    "prompt": "A Shiba Inu running through a snowy landscape",
    "imageConfig": {
      "imageSize": "4K"
    }
  }
}

パラメーター

• model（デフォルト：gemini-3-pro-image）：gemini-3-pro-image、gemini-3.1-flash-image、gpt-image-2、gpt-image-2.5-flare、gpt-image-2.5-sunburst、wan2.7-image-pro、wan2.7-image、または seedream-5-0-pro。プロバイダーはモデルから自動的に判定されます。生成前に GPT-Image-2.5 のサイズとコストを確認するには、estimate_credits を使用してください。
• imageConfig.imageSize：1K、2K、または 4K。wan2.7-image と seedream-5-0-pro は 4K に対応していません。wan2.7-image-pro も、参照画像が指定されている場合は 4K を使用できません。
• imageConfig.aspectRatio：1:1、2:3、3:2、3:4、4:3、4:5、5:4、9:16、16:9、21:9、1:4、4:1、1:8、または 8:1。GPT-Image-2 ではこのフィールドを省略して、サービスに選択を任せることができます。GPT-Image-2.5 は 1:1 から 21:9 までの 10 種類の比率に対応しています。Wan2.7 が対応しているのは 1:1、16:9、9:16、4:3、3:4 のみです。
• referenceImages：OpenAPI で指定できる数は、Gemini が最大 14 枚、GPT-Image-2／GPT-Image-2.5 が 4 枚、Wan2.7 が 9 枚、Seedream が 10 枚です。これらは API の上限であり、ウェブジェネレーターの別個のアップロード上限とは異なります。
• Seedream の精密編集：元画像を referenceImages に指定し、左上を原点とする絶対座標を使って、対象領域と変更内容を prompt に記述します。OpenAPI には、個別の mask パラメーターや region パラメーターはありません。
• outputMode（generate_image のみ）：hybrid（デフォルト。元画像を保存し、上限サイズ内のプレビューをインラインで返す）、file（元画像を保存し、メタデータのみを返す）、または inline（saveDir には保存せず、上限サイズ内のプレビューを返す。上流のレスポンスに元画像の URL がない場合に限り、元画像をデフォルトの復元用ディレクトリに保存する）。
• saveDir／timeoutSeconds（generate_image のみ）：hybrid／file モードでの保存先ディレクトリ、および非同期（4K）生成の最大待機時間です。

クレジットの概要

モデル	1K	2K	4K
gemini-3-pro-image	15	15	30
gemini-3.1-flash-image	10	10	20
gpt-image-2	4	6	10
wan2.7-image-pro	6	8	12（テキストから画像を生成する場合のみ）
wan2.7-image	4	6	非対応
seedream-5-0-pro	6	15	非対応

GPT-Image-2.5 Flare と Sunburst の価格は同じですが、インテグレーションガイドにはサイズ別のクレジット値が記載されていません。現在のコストと対応構成を確認するには、使用するモデルと imageConfig を指定して estimate_credits を呼び出してください。

無料利用

get_subscription は freeUsages を返します。このクォータは Labnana のウェブサイトおよび ListenHub アプリと共有されます。Nano Banana Pro の無料利用は 1K／2K のみに適用され、4K は常にクレジットを消費します。この無料クォータを利用する際、支払い履歴のないアカウントでは、優先度の低いレーンで再試行可能なビジーエラーが発生することがあります。再試行によって無料クォータやクレジットが消費されることはありません。

エラー

API エラーは { code, message } として返され、isError: true を含む MCP の結果として公開されます。

コード	意味	推奨事項
21007	API キーが無効です	LABNANA_API_KEY を確認してください。
26004	クレジットが不足しています	サブスクリプションを確認するか、プランをアップグレードしてください。
29003	パラメーターが無効です	必須フィールドとモデル固有の制限を確認してください。
29998	リクエストが多すぎます	20～30 秒のバックオフを設けて再試行してください。

開発

npm install
npm run typecheck
npm test

Labnana を呼び出したりクレジットを消費したりせずに、実際の単一ファイル MCP アプリを確認するには、npm run test:ui を実行し、http://127.0.0.1:4173/test/mcp-app-host.html を開いてください。ローカルホストは、生成された 640×360 PNG フィクスチャを公式 AppBridge 経由で送信するため、画像、ステータス、メタデータを視覚的に確認できます。

任意のライブ API チェックを行うには、リポジトリのルートにある .env に LABNANA_API_KEY を記述し、npm run test:real を実行してください。サブスクリプションを確認し、画像を生成したりクレジットを消費したりせずに、GPT-Image-2.5 の 2 つのバリアントの料金を見積もります。キーが設定されていない場合、テストはスキップされます。

実際の画像生成を検証するには、まず npm run build を実行し、その後 node test/e2e-generate.mjs を実行してください。クレジットを消費します。LABNANA_TEST_MODEL、LABNANA_TEST_IMAGE_SIZE、LABNANA_TEST_ASPECT_RATIO、LABNANA_TEST_PROMPT、LABNANA_OUTPUT_DIR を設定すると、モデル、出力、保存場所を選択できます。生成されたオリジナル画像は、デフォルトで labnana-images/ 以下に保存され、Git の対象外となります。

リンク

• Labnana 統合ガイド
• Labnana OpenAPI リファレンス
• Labnana モデル一覧
• クレジットガイド
• GitHub リポジトリ
• 公式 MCP レジストリ
• Glama ディレクトリ
• テクニカルサポート：[email protected]

ライセンス

Apache-2.0

コミュニティ

• LINUX DO
• 公式 MCP レジストリ
• Glama
• GitHub Issues