Skip to main content
Glama

labnana-mcp

npm version npm downloads CI node License MCP Registry labnana-mcp MCP server

An MCP server for the Labnana OpenAPI. It enables Claude, Claude Code, and other MCP clients to generate and edit images with Labnana.

Current OpenAPI models (product names mapped to the model parameter):

Product name

model

Provider

Resolutions

Best for

Nano Banana Pro

gemini-3-pro-image

Google

1K / 2K / 4K

In-image text, character consistency, high-fidelity output

Nano Banana 2

gemini-3.1-flash-image

Google

1K / 2K / 4K

Fast iteration and extreme aspect ratios

GPT-Image-2

gpt-image-2

OpenAI

1K / 2K / 4K

Spec-driven generation, layout control, illustration

GPT-Image-2.5 Flare

gpt-image-2.5-flare

OpenAI

1K / 2K / 4K

Faster generation

GPT-Image-2.5 Sunburst

gpt-image-2.5-sunburst

OpenAI

1K / 2K / 4K

Detail-dense images

Wan2.7 Image Pro

wan2.7-image-pro

Alibaba

1K / 2K / 4K¹

Photoreal and poster-style images

Wan2.7 Image

wan2.7-image

Alibaba

1K / 2K

Lower-cost everyday generation

Seedream 5.0 Pro

seedream-5-0-pro

ByteDance

1K / 2K

Coordinate-driven region editing and Chinese instructions

¹ wan2.7-image-pro supports 4K only for text-to-image; generations with reference images are limited to 2K. The OpenAPI reference lists GPT-Image-2.5 Flare and Sunburst; the model directory lists 1K / 2K / 4K and 10 aspect ratios, while the integration guide has not yet added the variants to its model list. Both variants support up to four reference images and cost the same. Check estimate_credits for the current price before generation.

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

Installation

Requires Node.js 20.9 or later.

Claude Code

  1. Create an API key in the Labnana API Keys console.

  2. Make LABNANA_API_KEY available in the environment used by Claude Code.

  3. Add the server:

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

The package can also be started directly with:

npx -y @exoticknight/labnana-mcp

DeepSeek Harness (DSH)

Add the server through DSH's official MCP client plugin. Pin 2.2.0 when you want the version shown by initialize to identify this MCP Apps-capable build:

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

DSH's MCP bridge can project supported ImageContent into the calling vision model. Version 2.1 also publishes a standard MCP Apps single-file View for generate_image and get_generation_task. An MCP Apps-capable DSH Web host renders the preview inline; a stock generic DSH tool card may still show the JSON fallback even though the model received the image. This is a client presentation limitation, not a lost generation result.

For a local source checkout, use the same row with command: node, an absolute args path to dist/index.js, and cwd set to this repository. Current stock DSH builds bridge MCP tools but do not consume MCP resources in the generic tool card. Without an MCP Apps host, model vision still works and the card falls back to JSON.

Cursor and VS Code

One-click install (replace the placeholder API key after installing):

Install in Cursor Install in VS Code

Claude Desktop and other MCP clients

Use an equivalent mcpServers configuration:

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

Local source checkout

npm install
npm run build

Then configure the server with the generated dist/index.js:

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

On Windows, use an absolute path such as:

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

Related MCP server: Nano Banana MCP

Configuration

The server reads the following environment variable:

Variable

Required

Description

LABNANA_API_KEY

Yes

Labnana API key.

LABNANA_OUTPUT_DIR

No

Default directory for saved images. Falls back to labnana-images/ under the working directory.

The command-line options below are also supported:

Option

Description

--api-key <key>

Provide the API key for a local process.

--base-url <url>

Override the default API endpoint, https://api.labnana.com.

--output-dir <dir>

Default directory for saved images.

Environment variables are recommended because command-line arguments may be visible in the local process list.

Tools

Tool

Description

generate_image

One-stop text-to-image / image-to-image / editing. Saves the original and returns a bounded MCP image preview, structured metadata, and JSON fallback by default; 4K requests poll internally.

estimate_credits

Estimate the credits required for a generation without generating an image.

get_subscription

Get subscription status, credit balances, and free usage information.

list_generation_tasks

List generation task history with pagination and optional status filtering.

get_generation_task

Get task details and public image URLs (useful after a generate_image timeout).

Usage

Generate an 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"
    }
  }
}

The default is outputMode=hybrid: the full original is saved to disk while a bounded MCP image preview, structuredContent, and equivalent JSON text are returned together. This provides progressive compatibility across Codex, Claude Code, Claude Desktop, and other MCP clients. Use saveDir to choose the target directory.

All 1K, 2K, 4K, and get_generation_task results use the same envelope:

{
  "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 }
    }
  ]
}

Image base64 appears only in standard MCP ImageContent, never duplicated into text or structured metadata. Full 4K originals are not inlined; previews have a maximum 1600-pixel edge and target a 2 MiB byte ceiling, while filePath/url locate the original.

Use referenceImages for image-to-image generation and editing. fileData.fileUri supports gs:// and https://; small images can be passed as base64 through inlineData.data.

4K requests automatically run as asynchronous tasks: the server creates the task, polls with rate-limit backoff, downloads and saves originals, and creates previews. If the wait exceeds timeoutSeconds (default 300), the result has status=pending and a taskId; this is not treated as generation failure. Fetch the final preview and original URL later with get_generation_task.

Credit estimation

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

Parameters

  • model (default: 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, or seedream-5-0-pro. The provider is derived from the model automatically. Use estimate_credits to confirm a GPT-Image-2.5 size and cost before generation.

  • imageConfig.imageSize: 1K, 2K, or 4K. wan2.7-image and seedream-5-0-pro do not support 4K; wan2.7-image-pro also disallows 4K when reference images are present.

  • 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, or 8:1. GPT-Image-2 may omit this field and let the service choose; GPT-Image-2.5 supports the ten ratios from 1:1 through 21:9; Wan2.7 supports only 1:1, 16:9, 9:16, 4:3, and 3:4.

  • referenceImages: OpenAPI allows up to 14 for Gemini, 4 for GPT-Image-2 / GPT-Image-2.5, 9 for Wan2.7, and 10 for Seedream. These are API limits, not the separate upload limits of the web generator.

  • Seedream precise editing: put the source image in referenceImages and describe the target region and change in prompt using absolute coordinates from the top-left origin. OpenAPI has no separate mask or region parameter.

  • outputMode (generate_image only): hybrid (default, save originals and inline bounded previews), file (save originals and return metadata only), or inline (do not save to saveDir; return a bounded preview, and persist the original to the default recovery directory only when the upstream response has no original URL).

  • saveDir / timeoutSeconds (generate_image only): target directory for hybrid/file mode, and the maximum wait for async (4K) generations.

Credit summary

Model

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 (text-to-image only)

wan2.7-image

4

6

Not supported

seedream-5-0-pro

6

15

Not supported

GPT-Image-2.5 Flare and Sunburst have the same price, but the integration guide does not list their size-specific credit values. Call estimate_credits with the intended model and imageConfig for the current cost and supported configuration.

Free usage

get_subscription returns freeUsages. This quota is shared with the Labnana website and ListenHub app. Nano Banana Pro free usage applies to 1K / 2K only; 4K is always charged in credits. When using that free quota, a never-paid account may receive a retryable busy error on the low-priority lane; retries do not consume the free quota or credits.

Errors

API errors are returned as { code, message } and exposed as MCP results with isError: true.

Code

Meaning

Recommendation

21007

Invalid API key

Check LABNANA_API_KEY.

26004

Insufficient credits

Check the subscription or upgrade the plan.

29003

Invalid parameters

Check required fields and model-specific limits.

29998

Too many requests

Retry with a 20–30 second backoff.

Development

npm install
npm run typecheck
npm test

To inspect the real single-file MCP App without calling Labnana or spending credits, run npm run test:ui and open http://127.0.0.1:4173/test/mcp-app-host.html. The local host sends a generated 640×360 PNG fixture through the official AppBridge so the image, status, and metadata can be checked visually.

For optional live API checks, put LABNANA_API_KEY in the repository-root .env and run npm run test:real. It checks the subscription and estimates both GPT-Image-2.5 variants without generating images or spending credits; the tests skip when the key is not configured.

To verify actual image generation, first run npm run build, then run node test/e2e-generate.mjs. This spends credits. Set LABNANA_TEST_MODEL, LABNANA_TEST_IMAGE_SIZE, LABNANA_TEST_ASPECT_RATIO, LABNANA_TEST_PROMPT, and LABNANA_OUTPUT_DIR to choose the model, output, and save location. Generated originals go under labnana-images/ by default and are ignored by Git.

License

Apache-2.0

Community

Available Tools

5 tools
estimate_credits预估图片生成所需积分A

根据模型、尺寸、宽高比等参数预估生成图片所需的积分。同步返回,不实际生成图片、不扣除积分。适合在批量生成或使用 4K 前先确认成本。

Inputs: prompt (required), model, imageConfig, referenceImages.

generate_image生成图片A

文生图 / 图生图 / 改图的一站式工具:默认保存完整原图,同时返回有大小上限的 MCP 图片预览、结构化元数据和 JSON 文本兜底。大图(4K)会自动走异步任务并在内部等待完成,无需手动轮询。支持 Gemini 系列、GPT-Image-2 / 2.5、Wan2.7、Seedream 5.0 Pro,模型由 model 参数选择,无需指定提供商。

Inputs: prompt (required), model, saveDir, outputMode, +3 more. Returns: error, images, status, taskId, +5 more

get_generation_task获取图片生成任务详情A

查询图片生成任务状态与结果。任务成功时返回统一结构化 envelope、有界 MCP 图片预览和原图 URL。generate_image 等待超时后可用返回的 taskId 在这里取回结果。

Inputs: taskId (required). Returns: error, images, status, taskId, +5 more

get_subscription获取订阅信息与积分余额B

获取当前 API Key 账户的订阅状态、可用积分(月度/永久/限时)、免费额度(freeUsages)与重置时间。

Inputs: no named parameters.

list_generation_tasks获取图片生成任务列表A

按创建时间倒序返回当前 API Key 用户的图片生成任务历史,可按状态过滤。

Inputs: page, status, pageSize.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4/5.0

    Scored across 5 tools

    Disambiguation5/5

    Each tool has a clearly distinct purpose: account subscription, credit estimation, image generation, task listing, and single-task retrieval. The only potentially related pair, list_generation_tasks and get_generation_task, is cleanly separated by list vs. single-task-by-ID semantics.

    Naming Consistency5/5

    All tool names follow a consistent snake_case verb_noun pattern: get_subscription, estimate_credits, generate_image, list_generation_tasks, get_generation_task. The repeated get_ prefix is used predictably for retrieval operations.

    Tool Count5/5

    Five tools is well-scoped for an image-generation API surface. Each tool corresponds to a meaningful operation without obvious redundancy or filler.

    Completeness4/5

    The surface covers account status, cost estimation, generation, task listing, and task retrieval, which supports the main workflows. Minor gaps such as task cancellation or model listing are not covered, but agents can work around these.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers