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 种宽高比，而集成指南尚未将这两个变体加入模型列表。两个变体均支持最多四张参考图，价格也相同。生成前请通过 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 单文件视图。支持 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。系统会根据模型自动确定提供方。生成前使用 estimate_credits 确认 GPT-Image-2.5 的尺寸和费用。
• 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 的十种比例；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 App，请运行 npm run test:ui 并打开 http://127.0.0.1:4173/test/mcp-app-host.html。本地主机通过官方 AppBridge 发送生成的 640×360 PNG 测试图像，以便直观检查图像、状态和元数据。

如需进行可选的实时 API 检查，请将 LABNANA_API_KEY 放入仓库根目录的 .env，然后运行 npm run test:real。该测试会检查订阅并估算 GPT-Image-2.5 的两个变体，不会生成图像或消耗积分；未配置密钥时会跳过测试。

如需验证实际图像生成，请先运行 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 Registry
• Glama 目录
• 技术支持：[email protected]

许可证

Apache-2.0

社区

• LINUX DO
• 官方 MCP Registry
• Glama
• GitHub Issues