labnana-mcp
Labnana MCP server lets MCP clients generate and edit images through Labnana while managing credits, subscriptions, and generation tasks.
Generate images from text prompts or reference images for image-to-image/editing workflows.
Use Gemini, GPT-Image-2, GPT-Image-2.5, Wan2.7, and Seedream models.
Run generation synchronously or asynchronously for large/4K or batch jobs.
Estimate credit cost before generating an image.
Check subscription status, credit balances, free usage, and reset timing.
List generation task history and retrieve task details/public image URLs.
Wait/poll for asynchronous generation tasks to complete.
Save original images and return bounded MCP previews plus structured metadata.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@labnana-mcp Generate an image of a cat astronaut floating in space."
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
labnana-mcp
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 |
| Provider | Resolutions | Best for |
Nano Banana Pro |
| 1K / 2K / 4K | In-image text, character consistency, high-fidelity output | |
Nano Banana 2 |
| 1K / 2K / 4K | Fast iteration and extreme aspect ratios | |
GPT-Image-2 |
| OpenAI | 1K / 2K / 4K | Spec-driven generation, layout control, illustration |
GPT-Image-2.5 Flare |
| OpenAI | 1K / 2K / 4K | Faster generation |
GPT-Image-2.5 Sunburst |
| OpenAI | 1K / 2K / 4K | Detail-dense images |
Wan2.7 Image Pro |
| Alibaba | 1K / 2K / 4K¹ | Photoreal and poster-style images |
Wan2.7 Image |
| Alibaba | 1K / 2K | Lower-cost everyday generation |
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
Create an API key in the Labnana API Keys console.
Make
LABNANA_API_KEYavailable in the environment used by Claude Code.Add the server:
claude mcp add labnana -- npx -y @exoticknight/labnana-mcpThe package can also be started directly with:
npx -y @exoticknight/labnana-mcpDeepSeek 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_KEYDSH'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):
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 buildThen configure the server with the generated dist/index.js:
claude mcp add labnana -- node <path-to-repo>/dist/index.jsOn Windows, use an absolute path such as:
claude mcp add labnana -- node C:/path/to/labnana-mcp/dist/index.jsRelated MCP server: Nano Banana MCP
Configuration
The server reads the following environment variable:
Variable | Required | Description |
| Yes | Labnana API key. |
| No | Default directory for saved images. Falls back to |
The command-line options below are also supported:
Option | Description |
| Provide the API key for a local process. |
| Override the default API endpoint, |
| Default directory for saved images. |
Environment variables are recommended because command-line arguments may be visible in the local process list.
Tools
Tool | Description |
| 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 the credits required for a generation without generating an image. |
| Get subscription status, credit balances, and free usage information. |
| List generation task history with pagination and optional status filtering. |
| Get task details and public image URLs (useful after a |
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, orseedream-5-0-pro. The provider is derived from the model automatically. Useestimate_creditsto confirm a GPT-Image-2.5 size and cost before generation.imageConfig.imageSize:1K,2K, or4K.wan2.7-imageandseedream-5-0-prodo not support 4K;wan2.7-image-proalso 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, or8:1. GPT-Image-2 may omit this field and let the service choose; GPT-Image-2.5 supports the ten ratios from1:1through21:9; Wan2.7 supports only1:1,16:9,9:16,4:3, and3: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
referenceImagesand describe the target region and change inpromptusing absolute coordinates from the top-left origin. OpenAPI has no separatemaskorregionparameter.outputMode(generate_imageonly):hybrid(default, save originals and inline bounded previews),file(save originals and return metadata only), orinline(do not save tosaveDir; 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_imageonly): target directory forhybrid/filemode, and the maximum wait for async (4K) generations.
Credit summary
Model | 1K | 2K | 4K |
| 15 | 15 | 30 |
| 10 | 10 | 20 |
| 4 | 6 | 10 |
| 6 | 8 | 12 (text-to-image only) |
| 4 | 6 | Not supported |
| 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 |
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 testTo 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.
Links
Technical support: support@marswave.ai
License
Community
Available Tools
5 toolsestimate_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
Scored across 5 tools
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.
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.
Five tools is well-scoped for an image-generation API surface. Each tool corresponds to a meaningful operation without obvious redundancy or filler.
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
Related MCP Connectors
MCP server for Midjourney AI image generation and editing
MCP server for Qwen Image 3 AI image generation
MCP server for Flux AI image generation
MCP server for ByteDance Seedream AI image generation
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceAn MCP server that provides image generation using Google's Nano Banana Gemini models, with additional tools for background removal, upscaling, and format conversion via deterministic post-processing.1MIT
- AlicenseNot gradedqualityCmaintenanceMCP server for Google's Nano Banana image generation models (Gemini). Generate and edit images via natural language.1MIT
- AlicenseAqualityDmaintenanceMCP server for AI image generation and editing using Google Gemini image models.71,647 npmMIT
- AlicenseAqualityDmaintenanceMCP server for generating and editing images using Google Gemini API. Supports text-to-image generation, image editing, and image description.319 npmMIT