Local MCP server for ecommerce image generation/editing and design/task workflows, exposing 21 tools, 9 resources, and 6 prompts.
Generate or edit product main images, detail-page images, scene images, posters, and reference-based images with paid model calls.
Run synchronous generation/waiting or asynchronous task submission, querying, waiting, cancellation, and safe retry.
Save generated images locally and return absolute paths, dimensions, byte sizes, MIME types, and SHA256 hashes.
Use free tools to inspect models/configuration, plan ecommerce image prompts, and inspect local/HTTP reference images.
Plan, version, confirm, submit, and query ecommerce designs for main images, detail modules, and SKUs.
Analyze and adapt reference/competitor images into replica plans, then export or validate replica prompts.
Build, export, and validate shared-style product-suite prompt sets for main + detail + SKU designs.
Use idempotent task identities, local SQLite-backed state, file-integrity checks, and cautious retry rules to avoid duplicate charges.
Supports OpenAI-compatible image APIs: models can be routed through the OpenAI Chat format or the DALL·E endpoints (Generations for text-to-image and, for nano-banana-pro, Edits for reference-image editing), including resolution variants such as 2k/4k.
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., "@zhenzhen-nanobanana-mcp Create a product main image of a ceramic mug on a light wood table"
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.
v0.3.1 面向家居日用电商，保留 21 Tools、9 Resources、6 Prompts 及同步/异步出图。本补丁修复队列热路径重复结构事务、阻塞 stdio 的持久文件写入和 Windows SQLite 文件占用；不改变公开工具、模型或收费防重契约。功能见设计工作流、竞品复刻、同款整套模板和队列可靠性。
发布状态以正式 Release及其资格记录为准；草稿或记录缺失时安装器停止。现用 D 盘安装仍为 v0.3.0，本次发布不自动更新它。原始验收证据、历史版本和图片保持不变。
用于家居日用百货电商绘图的本地 MCP Server：商品主图、详情页、场景图、营销海报和参考图编辑。Agent 一次可提交 1–20 项任务，选择异步立即返回，或同步等待完成并落盘后返回；默认并发 5，图片自动保存到本机。生成和编辑会产生供应商费用。
参考图可直接使用本机可读图片绝对路径或公开 HTTP/HTTPS 图片直链，无需搬入 input。服务会检查图片内容、大小及网络地址；不自动上传店铺或保证平台审核通过。
成员安装目标为 v0.3.1，默认目录 D:\MCP\zhenzhen-nanobanana-mcp。精确标签 SHA 与成功 main CI 来自正式附件 release-eligibility.json；下面的示例逐项核对，不猜测提交。本次修复的已验收代码基线为 e0a80b53accce98ab8819e2812d871ceb23a1d7a，它不作为本版最终发布标签的提交。
需要 Windows x64、Git、PowerShell 7、uv（已验证 0.12.9）。项目精确使用 Python 3.12.14，由 uv 按锁定声明准备；FastMCP 4.1.0、MCP SDK 2.3.0。首次安装需访问 GitHub、Python 下载源和 PyPI；绘图及图片下载另需业务网络。Linux/macOS/WSL 尚未完成安装验收。
Related MCP server: universal-image-mcp
在 PowerShell 7 执行以下首次安装步骤。只创建父目录，clone 自动创建项目目录；已有安装请按升级与迁移处理。
$ErrorActionPreference = 'Stop'
$ProjectDir = 'D:\MCP\zhenzhen-nanobanana-mcp'
if (Test-Path -LiteralPath $ProjectDir) { throw '目录已存在，请按手册更新，不能覆盖。' }
New-Item -ItemType Directory -Path (Split-Path -Parent $ProjectDir) -Force | Out-Null
git clone --branch v0.3.1 --single-branch 'https://github.com/tsyecommercialdesigner-cloud/zhenzhen-nanobanana-mcp.git' $ProjectDir
if ($LASTEXITCODE -ne 0) { throw '仓库获取失败。' }
$Evidence = & (Join-Path $ProjectDir 'scripts\install-from-github.ps1') -Tag v0.3.1 -VerifyOnly
$ExpectedCommit = $Evidence.Commit
$ActualCommit = git -C $ProjectDir rev-parse HEAD
if ($LASTEXITCODE -ne 0 -or $ActualCommit -cne $ExpectedCommit -or $Evidence.Tag -cne 'v0.3.1') { throw '正式发布记录不匹配。' }
uv --directory $ProjectDir sync --locked --no-dev
if ($LASTEXITCODE -ne 0) { throw '运行依赖安装失败。' }
pwsh -NoProfile -File (Join-Path $ProjectDir 'scripts\smoke-test.ps1')
if ($LASTEXITCODE -ne 0) { throw '隔离协议检查失败。' }
$EnvPath = Join-Path $ProjectDir '.env'
if (!(Test-Path -LiteralPath $EnvPath)) {
[IO.File]::Copy((Join-Path $ProjectDir '.env.example'), $EnvPath, $false)
}
Start-Process -FilePath 'notepad.exe' -ArgumentList ('"{0}"' -f $EnvPath) -ErrorAction Stop在编辑器中填写 ZHENZHEN_NANOBANANA_API_KEY=，保存为 UTF-8；使用原始密钥，不加 Bearer ，不写入共享命令或 Host 模板。仅当字段缺失时按 项目 .env → 进程环境 → Windows 当前用户环境 回退；空值、非法值、重复或解析错误会阻止启动。已有 .env 和业务数据在升级时保留。完整发布记录核验、权限和回滚步骤见手册。
协议检查使用隔离假配置，不产生绘图费用；通过后在所用 Host 合并服务配置。日常启动入口为：
uv --directory 'D:\MCP\zhenzhen-nanobanana-mcp' run --no-sync python -m zhenzhen_nanobanana_mcp
if ($LASTEXITCODE -ne 0) { throw 'MCP 服务退出失败，请检查 stderr。' }stdio 等待输入时没有普通输出属于正常状态。Host 负责启动子进程，无需同时手动常驻；启动不安装依赖或拉取代码。
客户端 | 配置入口 |
Cherry Studio | 本地 JSON 模板，导入/填写后保存、启用并绑定助手 |
Codex | TOML 模板，合并到实际 Codex 配置后重载服务 |
Claude Code | 项目 JSON 模板，按所选项目作用域添加；Claude-3p 未作为已验证适配交付 |
原生 DSH / DSH App / Multica | 同一 YAML 模板，分别合并到 web / desktop / multica 的独立 patch |
完整的添加、备份、保存、启用、工具发现和权限步骤见客户端配置。DSH 章节按新规范提供三份 profile 的存在检查、唯一备份、打开命令与空列表/已有 patch 合并方式；不覆盖其他插件，不改共享 bundle。HTTP/代理配置不适用于本项目。
v0.3.1 提供 21 个工具，支持同步与异步出图，详见资源与参数：
工具 | 用途 |
| 免费核对模型、配置与能力 |
| 免费规划商品图提示词 |
| 提交生成/编辑任务，等待完成并落盘后返回，会收费 |
| 持久化后立即返回，后台并发生成/编辑，会收费 |
| 查询已有任务及图片路径 |
| 只等待已有任务，不新增绘图请求 |
| 取消未发出的任务；已可能发出时标记不确定 |
| 只读查询旧批次 |
| 显式重试满足安全条件的已有任务；不确定收费状态不得盲目重提 |
| 免费读取本机或公开URL图片，交给Host观察 |
| 免费保存版本化设计底稿，缺少信息时返回待补问题 |
| 记录用户对当前版本的确认，不代表收费授权 |
| 提交已确认设计，须另提供收费授权 |
| 免费查询设计、已有任务及图片路径 |
| 保存参考图拆解与逐图复刻方案 |
| 只读导出参考复刻提示词 |
| 记录Agent对已有结果图的复核，不自动重画 |
| 免费构造主图、详情页、SKU共享规范方案 |
| 只读导出已校验的整套提示词 |
| 免费构造共享规范竞品复刻方案 |
| 只读导出已校验的竞品复刻提示词 |
调用免费 list_models 核对配置，提供已核实的商品事实与参考图。
用免费 plan_ecommerce_images 规划并审阅提示词；出图前确认收费授权。
为每项提供稳定的 (checkpointer, thread_id, task_id)，选择异步 submit_image_tasks 立即登记，或同步 generate_images 等待本组完成、图片落盘后返回。
异步任务用 get_image_tasks 立即查询；已有任务也可用 wait_image_tasks 等待，成功后使用返回的图片绝对路径。
同步生成/等待的 wait_timeout_seconds 默认600，严格整数1–1200秒，包含排队时间；Host工具超时应更长并预留传输开销。等待超时返回 isError=true、wait_timed_out=true 及当前状态和已完成图片，只结束此次等待，后台继续。客户端取消也不主动取消队列任务，按原身份继续等待或查询，不能换编号重提；如果Host关闭整个MCP进程，仍受原有恢复规则约束。
相同身份与相同参数跨同步/异步入口复用记录；参数冲突整组拒绝新增。queued/preparing/running 只表示尚未完成；failed/unknown、超时或取消不保证未收费，不自动换编号重试。防重范围为同一实际输出目录，保留 SQLite 与图片，不删除账本绕过幂等。此外提供6 Prompts、9 Resources；完整名称与设计流程见手册及对应专题文档。
默认模型 gemini-nano-banana-2.1，自动使用 DALL·E Generations；nano-banana-pro 仅 DALL·E，支持 Generations/Edits；Flash-lite 仅 Gemini/Chat。两个 banana 家族支持基础版及 -2k/-4k。显式分辨率长边 ≤1024 用基础版、≤2048 用 2k、>2048 用 4k；Flash-lite 不路由。此规则只选择模型，不保证精确输出像素，完整接口矩阵见手册。
21工具隔离Host验收与DSH Agent实际看图记录真实Host后端验证。原最小DSH profile因缺附件/视觉路由未通过看图；补齐后使用codeproxy-anthropic / claude-sonnet-5-5完成CLI Agent识图，Desktop GUI仍未验证。
历史16图业务验收只证明相应模型/接口的流程和文件校验，7图Agent通过、9图需修订，不等于全部可上架。新版本发布说明及当前边界见v0.3.1；旧v0.2.2安装验收与D盘记录保留原范围。全部模型/变体、真实故障恢复及Desktop GUI不因发布而视为通过。
维护者遵循分支 → PR → Windows CI → 评审 → 合并；发布单独授权，先创建草稿，核对后才公开。开发安装使用 uv sync --locked、检查使用 uv run --no-sync python scripts/check.py；成员只需锁定运行依赖。任务状态见交付任务。
免费构造同一商品主图+详情+SKU整套绘图提示词，Pydantic校验后保存新版本；不收费出图。
先读nanobanana://templates/product-suite和styles/main/detail/sku，或product_suite_brief。 Agent先观察实图、分析需求/对标、策划文案和构图。suite.style是全套唯一风格来源： 颜色角色、画面/光线、文案语气/术语、字体家族/字重、排版层级比例；brief.style不参与整套编译。 frames选择模板并填写本图内容，不接受逐图style覆盖。1–8张主图、8–15屏详情、每个SKU一图。 主图一图一信息；详情opening→solution→产品/证据→closing；SKU需真实独立实图/相同属性字段。 画幅按suite.canvases分类型设置；未设分辨率继承brief.resolution；仅使用list_models中三类模型。 返回design/统一style_digest/逐图task.prompt及执行参数，缺需求返回needs_input和questions，无提示词。 修改传当前expected_revision和完整brief，旧确认失效；不要用普通edits修改整套。 展示并研讨→confirm_ecommerce_design锁定版本→明确收费授权后submit_ecommerce_design。 实际提交从保存的类型化方案重新校验编译，与返回提示词相同；不回填或替换task.prompt。
Inputs: brief (required), design_id (required), expected_revision. Returns: design, prompts, style_digest
免费构造新版竞品复刻提示词：单图/同类系列或主图+详情+SKU整套，Pydantic校验后保存；不出图。
先读取nanobanana://templates/reference-replica、reference-analysis或reference_replica_brief。 Agent分别观察源图和商品，写analysis/跨类目adaptations；reference_replica.style统一颜色/画面/光线/ 文案/字体/层级比例，frames只写本图内容与composition，不接受scene/style等逐图覆盖。 scope=series时brief.kind与各frame.kind一致；product_suite时brief.kind=main，主图/详情/SKU三类齐全。 frame使用已有12模板的信息目的，但composition由Agent适配参考；SKU需自身实图/真实属性/合法事实ID。 返回design、共享style_digest与每图task.prompt/实际三模型配置/input_images角色和SHA；缺信息无可执行提示。 导出与实际执行共用ReplicaDrawingPrompt→ImageTask校验和编译器。下一步只读导出研讨→confirm_ecommerce_design →明确收费授权后submit_ecommerce_design。新版本须重新确认，不能用普通edits或替换task.prompt。 原plan_reference_replica/export_reference_replica保留兼容历史replica，不原地转换旧任务。
Inputs: brief (required), design_id (required), expected_revision. Returns: design, prompts, style_digest
取消指定任务；queued/preparing不发图，running只停止本地等待并标unknown，不保证远端停止/退款。
Inputs: task_ids (required), thread_id (required), checkpointer (required). Returns: tasks, thread_id, next_cursor, checkpointer
仅在用户明确确认当前商品事实、逐图文案与排版后记录方案确认；不收费、不提交。
必须传本次展示的revision/digest及用户确认说明，user_confirmed=True；旧稿/缺信息拒绝。 Host不能自行替用户确认，任何改稿须再次展示并确认。收费授权另在提交时提供。
Inputs: digest (required), revision (required), design_id (required), confirmation_note (required), +1 more. Returns: brief, notes, assets, digest, +8 more
只读重新导出整套的已校验提示词、统一风格摘要和实际执行配置；不改版本、不确认、不出图。
默认当前版，可查看历史版；历史版不能用于当前提交。与实际执行共用DrawingPrompt/ImageTask校验和编译器。 prompts.task给出商品冻结图及SHA256、三模型实际选档、接口与分类型画幅；不得绕过确认/收费流程直接回填通用出图入口。
Inputs: design_id (required), revision. Returns: design, prompts, style_digest
免费导出1–20项完整可执行Markdown和附图顺序，用于研讨并适配本服务三个模型；不提交、不批准。
严格保留Visual Schema/Scene Configuration/Layout Configuration/Textual Contents， 可选Logical Structure，实际提交共用相同编译器。input_images必须按角色顺序附上。 prompt_target/execution_model均按本服务实际模型及分辨率选档；api_format/endpoint展示真实接口。 实际出图后用inspect_design_images查看结果、review_reference_replica记录证据，再由用户决定停止或修订。
Inputs: design_id (required), panel_ids (required), revision. Returns: items, notes, digest, endpoint, +7 more
只读导出新版共享复刻的已校验完整Markdown、统一风格摘要、实际任务配置与有序图像角色；不批准、不收费。
当前/历史版本可查，只有当前已确认版本能提交；最多71项的整套可导出，执行分批每次最多20项。 每项task.prompt保持原Visual Schema/Scene/Layout/Text/可选Logical结构，input_images按图1风格、图2+商品顺序。 与真实提交使用同一编译器；不要将task回填通用出图入口绕过版本确认或收费授权。
Inputs: design_id (required), revision. Returns: design, prompts, style_digest
同步生成/编辑1–20项（会收费）：等待本组全部终态且成功图片落盘后返回。
任务参数与submit_image_tasks相同，支持同样的模型、比例和本机/URL参考图。 与异步入口共用三元组、防重、队列和并发限额；相同任务不重复提交。 wait_timeout_seconds默认600，严格整数1–1200，包含排队时间。 全部成功才isError=false；失败保留所有结果。等待到期返回isError=true、 wait_timed_out=true及当前状态，不取消后台任务。Host超时/取消也不保证停止上游。 请保留原三元组，用get_image_tasks查询或wait_image_tasks继续等，不换编号重交。
Inputs: tasks (required), thread_id (required), checkpointer (required), wait_timeout_seconds. Returns: tasks, thread_id, next_cursor, checkpointer, +1 more
读取已登记批次及保存路径，不调用上游、不重发请求；未完成/失败返回 isError。
Inputs: request_id (required). Returns: items, model, reused, status, +5 more
只读查询当前/历史版本、待补信息、未提交图片及已有任务/图片绝对路径，不重新出图。
已落盘结果包含尺寸、字节数、SHA256；失败/unknown/cancelled返回isError并保留所有结果。 没有任务或queued/running不代表设计已完成。继续等待/取消用返回的原队列三元组。
Inputs: design_id (required), revision. Returns: tasks, design, thread_id, checkpointer, +2 more
查询持久任务与图片绝对路径，不重新提交上游。可按task_ids筛选或用next_cursor分页。
queued/preparing/running正常返回；failed/unknown/cancelled返回isError并保留全部状态。 checkpointer是本地SQLite字符串命名空间，不是路径、LangGraph对象或认证凭据。
Inputs: thread_id (required), checkpointer (required), limit, cursor, +1 more. Returns: tasks, thread_id, next_cursor, checkpointer
免费读取1–4张产品图/对标图并以MCP图片内容交给Host观察，不调用视觉或绘图模型。
输入本机绝对路径或公开图片直链；沿用格式/大小/公网URL检查，不抓网页。 Host应记录可见外形、配色、比例、布局；不得从图推断性能参数或照搬竞品事实。
Inputs: images (required). Returns: images
列出三个模型家族及已有2k/4k变体（共7个标识）、API格式、目录与限制；不联网、不返回密钥。
Inputs: no named parameters. Returns: models, input_dirs, output_dir, api_formats, +17 more
免费保存主图/详情页/SKU设计底稿；按需求→参考→文案与排版研讨推进，不出图。
新建expected_revision=0，修改须传当前revision、完整brief和可选逐图edits；每次产生新版本，需重新确认。 先查看产品实图，填写visual_observations和有source的已核实facts；对标填写benchmarks， 或向用户索取参考，或记录用户明确不用参考的理由。缺信息返回needs_input和questions。 main默认5张、detail默认10屏、sku一版本一图且需各自实图。尺寸/比例按平台与用户确认，非自动合规。 返回逐图标题、正文、事实引用、主体与排版；先展示用户研讨，不得把底稿视为批准。
Inputs: brief (required), design_id (required), edits, expected_revision. Returns: brief, notes, assets, digest, +8 more
免费生成可审阅的主图/详情页/场景/海报绘图计划。
scene: main 主图；detail 详情模块；scene 家居场景；poster 营销海报。 selling_points: 已核实事实，可为空列表；不自动编造商品信息。 count: 图片项数，详情页推荐 6 项；比例由用户决定。 reference_images: 原样传入计划，真正出图前才读取/下载并校验。 resolution: 可选显式 width/height 像素尺寸，原样传入每项用于模型路由。
Inputs: product_name (required), selling_points (required), count, scene, +5 more. Returns: items, notes, scene, product_name
免费保存Agent完成的竞品拆解、跨类目适配与目标frames；不代替Agent识图，不出图。
新方案优先build_reference_replica_prompts，以共享风格保持同款图组统一；本工具兼容旧replica。
先inspect_design_images查看参考和商品；分析风格/构图/光色/细节/互动/文案/信息顺序， 给出源/目标类目及保留/适配/替换/舍弃理由。frames是Agent写出的完整目标控制结构， 不自动复制源文案。open_questions使方案needs_input，阻止确认/出图。 每项图1仅风格，图2+为商品；商品事实只能引用brief.facts，SKU须明确绑定本版本。 frames决定图片数，支持单张详情图。brief.replica可省略，由独立replica参数给出。 修改传当前expected_revision、完整brief/replica；旧确认失效。 下一步export_reference_replica展示完整提示→confirm_ecommerce_design→授权后submit_ecommerce_design。 Resource nanobanana://reference-replication 和Prompt reference_replication_brief说明完整循环。
Inputs: brief (required), replica (required), design_id (required), expected_revision. Returns: brief, notes, assets, digest, +8 more
按原幂等键重排1–20项安全阶段；不会重发结果不明的收费请求。
safe_to_retry表示存在原响应可恢复，或确定未发送；成功/进行中的项直接复用。 有响应时只重新下载/落盘；连接前失败可按同一供应商Idempotency-Key重试。 文件校验失败需repair_files=True，保留损坏文件后从原响应修复，绝不重画修复。 任一不安全项使本批全不重排；POST已可能发送且无检查点时先核对费用，禁止换ID盲目重提。
Inputs: task_ids (required), thread_id (required), checkpointer (required), repair_files. Returns: tasks, thread_id, next_cursor, checkpointer
保存Host Agent观察真实出图后的六维复核，不是服务器识图评分，也不自动重新出图。
新reference_replica同时核对共享style及已观察的同组其他图片，证据写入style_fidelity。
先get_ecommerce_design取路径/hash，再inspect_design_images看图；与参考/商品逐项比较： 产品忠实度、风格、目标类目、布局光感、实际文字、事实。每项需具体证据，revise/uncertain需修正动作。 校验图片属于本设计版本任务且当前文件哈希相同。结果和next_steps可从get_ecommerce_design读取。 agent_passed仍需向用户展示验收；修改后重新plan/confirm/授权，不能自动换ID重画。
Inputs: task_id (required), revision (required), design_id (required), assessment (required), +1 more. Returns: outcome, task_id, reviewer, revision, +5 more
将已确认方案中明确选择的1–20图提交后台收费绘图；需用户明确收费授权。
所有图使用批准版本的商品图副本、文案、排版和模型；当前revision/digest必须匹配。 固定映射checkpointer=ecommerce-design、thread_id=design_id、task_id=r{revision}-{panel_id}， 可分批提交超过20图的方案；重复同图复用原任务，不新增收费请求。 用get_ecommerce_design获取落盘路径；wait_image_tasks等待原任务。失败/超时勿换设计编号重提。
Inputs: digest (required), revision (required), design_id (required), panel_ids (required), +1 more. Returns: tasks, thread_id, next_cursor, checkpointer
批量登记1–20个后台图像任务并立即返回，不等待绘图/下载（会在后台收费）。
每项task_id在checkpointer/thread_id内唯一且稳定，同内容复用；任何冲突全批不新增。 每项可选model/api_format(auto)/endpoint(auto)；变体按显式resolution路由。 Flash-lite仅Gemini/Chat；nano-banana-pro仅DALL·E；gemini-nano仅DALL·E Generations/Gemini/Chat。 查询get_image_tasks；queued/preparing/running是正常状态，unknown不能盲目重交。 MCP进程关闭时未发送任务可在重启后继续，已可能发送任务不自动重试。
Inputs: tasks (required), thread_id (required), checkpointer (required). Returns: tasks, thread_id, next_cursor, checkpointer
等待1–100个已有任务，不提交、不重新出图；所有指定任务终态后返回结果。
task_ids必填且不重复；不存在或错误命名空间报错。 等待时限默认600秒，严格整数1–1200；到期isError=true、wait_timed_out=true， 保留当前状态和已完成图片，后台继续。客户端取消只停止本次等待。 终态failed/unknown/cancelled是isError；查询get_image_tasks不等待。
Inputs: task_ids (required), thread_id (required), checkpointer (required), wait_timeout_seconds. Returns: tasks, thread_id, next_cursor, checkpointer, +1 more
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
Scored across 21 tools
The set has several overlapping surfaces: plan_ecommerce_images vs plan_ecommerce_design, submit_image_tasks vs generate_images, get_image_tasks vs get_batch_result vs get_ecommerce_design, and legacy plan/export_reference_replica vs newer build/export_validated_reference_replica. Detailed descriptions help, but an agent must still infer which workflow/version is active, making misselection likely.
Most tools follow a readable snake_case verb_noun pattern such as submit_image_tasks, get_image_tasks, cancel_image_tasks, and confirm_ecommerce_design. Minor inconsistencies exist in singular/plural usage and in legacy vs validated export names, but the overall convention is predictable.
With 21 tools, the set is borderline heavy and includes parallel legacy/new reference-replica paths plus multiple planning/export variants. The count is defensible for a complex image-generation workflow, but several tools feel like duplicate surface area rather than independently necessary operations.
The surface covers the main lifecycle: planning, confirmation, submission, polling/waiting, cancellation, retry, inspection, export, and review. There are minor gaps around unified discovery of all designs/batches and cleanup/delete operations, but core workflows are represented.
Hosted MCP server for AI photo editing: nothing to install, no desktop photo editor needed.
MCP server for Qwen Image 3 AI image generation
MCP server for ByteDance Seedream AI image generation
Screenshots, PDFs, image editing, QR codes, email validation and more through one hosted MCP server.
