使用说明

项目简介

MCP NanoBanana 是一个基于 MCP 的服务器实现，聚焦通过 AceDataCloud 的 Nano Banana 模型提供图像生成与编辑能力，并将相关的工具、提示模板暴露给集成的大语言模型（LLM）客户端。它通过 MCP 规范处理请求与响应，支持多传输模式，以及会话管理与安全校验，便于在 Claude Desktop、VS Code 等 MCP 客户端中使用。

主要功能点

MCP 核心能力：实现基于 MCP 的请求/响应处理，支持 JSON-RPC 风格通信，提供统一的服务器入口。
工具注册：提供用于图像生成与编辑的工具接口，如 nanobanana_generate_image、nanobanana_edit_image、nanobanana_get_task、nanobanana_get_tasks_batch。
提示模板：提供用于指导 LLM 调用工具的提示模板，如 nanobanana_image_generation_guide、nanobanana_prompt_writing_guide、nanobanana_workflow_examples。
传输模式：支持本地 STDIO 传输和 HTTP 传输两种模式，HTTP 模式可通过 Bearer Token 进行鉴权。
会话与令牌管理：在 HTTP 模式下，从请求头提取 Bearer token 以进行上游 API 调用，在 STDIO/默认模式下使用环境变量中的 API Token。
服务器搭建与部署：提供直接运行入口 main.py，包含快速启动、健康检查、日志输出等开发友好特性；也支持通过 Docker/部署配置进行自定义环境部署。

安装步骤

确保 Python 3.10+ 环境就绪。
获取代码：克隆仓库或下载源码。
安装依赖并安装本项目：
- 运行命令：pip install -e .
配置环境变量（在根目录创建或复制 .env.example 为 .env，并填写对应值）：
- ACEDATACLOUD_API_TOKEN：AceDataCloud 的 API 令牌（必须）
- 其他可选：ACEDATACLOUD_API_BASE_URL、NANOBANANA_REQUEST_TIMEOUT、LOG_LEVEL 等
启动服务：
- 本地标准输入输出模式（stdio，默认）：
  - mcp-nanobanana-pro
- HTTP 模式（需要路由/端口暴露，示例通常如下）：
  - mcp-nanobanana-pro --transport http --port 8000

服务器配置（MCP 客户端需要的最低信息）

以下 JSON 配置用于 MCP 客户端配置服务器启动与连接。字段说明如下：

server_name：服务器名称，客户端用来标识对应的 MCP 服务器
command：启动服务器的命令或可执行程序
args：启动命令的参数列表
env（可选）：启动时需要的环境变量（如 API 令牌）

{ "server_name": "nanobanana", "command": "mcp-nanobanana-pro", "args": ["--transport", "stdio"], "env": { "ACEDATACLOUD_API_TOKEN": "your_token_here", "ACEDATACLOUD_API_BASE_URL": "https://api.acedata.cloud" } // 注：以上 env 字段用于本地直连模式的上游 API 认证，HTTP 模式下也可在请求头中提供 Bearer token }

基本使用方法

本地开发与调试
- 复制并填写 .env 中的 API 令牌
- 运行 mcp-nanobanana-pro，服务器自启动并监听标准输入/输出
- 客户端通过 MCP 协议与服务器进行请求与响应
HTTP 远程模式
- 以 HTTP 传输方式启动：mcp-nanobanana-pro --transport http --port 8000
- 客户端通过 Bearer Token 进行鉴权，请在请求头中加入 Authorization: Bearer <token>
- 远程健康检查和初始化请求参照 README 示例
客户端集成要点
- 支持的工具：nanobanana_generate_image、nanobanana_edit_image、nanobanana_get_task、nanobanana_get_tasks_batch
- 支持的提示模板：nanobanana_image_generation_guide、nanobanana_prompt_writing_guide、nanobanana_workflow_examples
- 可通过 Claude Desktop、VS Code 等 MCP 客户端读取/执行工具与提示模板
- 如需异步回调，请在请求中提供 callback_url，服务器将返回任务 ID 并在完成时回调

其他

开发与测试：仓库内含单元测试与开发脚本，使用 pytest 进行测试与代码质量工具（ruff、mypy）等
部署：支持 Docker 部署（如 README 中所示的镜像 ghcr.io/acedatacloud/mcp-nanobanana:latest）

注意事项

在本地模式下需要 ACEDATACLOUD_API_TOKEN，有效 token 是必需的
在 HTTP 模式下，请确保 Authorization 头部携带 Bearer token，服务器会从该头部获取令牌用于上游请求

MCP NanoBanana 服务端实现