内容
# Gemini 图片服务器
一个独立的、用户范围的 [模型上下文协议](https://modelcontextprotocol.io) 服务器，允许 Claude Code **生成和编辑图片**，使用谷歌的 Gemini 图片模型（**Nano Banana** / **Nano Banana Pro**）和 **Imagen 4** — 运行在 **Vertex AI** 上，使用 **应用程序默认凭证（ADC）**。无需 API 密钥，无需 JSON 密钥文件。
- **默认模型：** `nano-banana` = Gemini 2.5 Flash 图片（GA）。
- **也支持：** `nano-banana-pro`（Gemini 3 Pro 图片，预览版）和 `imagen-4*` 系列。
- **传输方式：** 标准输入输出（本地）或可流式传输的 HTTP（远程），通过官方 Python MCP SDK（FastMCP）。
- **身份验证：** 仅限 Vertex AI + ADC。您需要提供自己的 GCP 项目。
## 快速开始（一步到位，无需克隆）
`uvx` 直接从 GitHub 获取并运行服务器 — 无需克隆或安装。在单个命令中将其注册到 Claude Code 用户范围：
```bash
claude mcp add gemini-image -s user \
-e GOOGLE_CLOUD_PROJECT=您的GCP项目ID \
-- uvx --from git+https://github.com/someshwarpatil/gemini-image-mcp.git gemini-image-mcp
```
然后使用 ADC 进行身份验证，并重启 Claude Code：
```bash
gcloud auth application-default login
```
**前提条件：** Python 3.12 + [uv](https://docs.astral.sh/uv/)，[gcloud CLI](https://cloud.google.com/sdk/docs/install)，以及具有 **启用 Vertex AI API** 的 GCP 项目。通过 `claude mcp list` / `claude mcp get gemini-image` 进行验证。
## 工作原理
服务器作为独立进程运行（Claude Code 通过标准输入输出启动它）。由于它是独立进程，**无法访问客户端的每会话临时目录** — 因此每个工具都需要明确指定 `output_dir`。全分辨率 PNG **始终保存到磁盘**，其**绝对路径始终被返回**。只有当 `return_image=True` 时，才会返回小尺寸的缩略图，以保护客户端的 token 预算（完整分辨率的 MCP 图片可能需要 ~15-25k tokens）。
## 从克隆中设置（用于开发）
```bash
git clone https://github.com/someshwarpatil/gemini-image-mcp.git
cd gemini-image-mcp
# 一条命令：同步依赖项 + 检查 ADC + 注册到 Claude Code。
GOOGLE_CLOUD_PROJECT=您的GCP项目ID ./scripts/setup.sh
```
`scripts/setup.sh` 运行 `uv sync`，检查 ADC，并注册服务器到用户范围（幂等 — 安全地重新运行）。或者手动执行：
```bash
uv sync
gcloud auth application-default login # 一次 ADC；无需 API 密钥，无需 JSON 密钥文件
export GOOGLE_CLOUD_PROJECT=您的GCP项目ID
```
更喜欢使用文件而不是 shell 导出？复制 `.env.example` → `.env` 并填写您的值（`.env` 被 gitignore）。
## 环境
| 变量 | 默认值 | 用途 |
|---|---|---|
| `GOOGLE_CLOUD_PROJECT` | _(自动从 ADC / gcloud 检测)_ | 提供 Vertex 图片模型的 GCP 项目。 |
| `GOOGLE_CLOUD_LOCATION` | `global` | **Gemini** 模型的 Vertex 位置。Gemini 图片模型 **仅在 global 上可用** — 保留为 `global`。 |
| `GEMINI_IMAGE_IMAGEN_LOCATION` | `us-central1` | **Imagen** 模型的 Vertex 位置（Imagen **不在 `global` 上提供**）。 |
| `GEMINI_IMAGE_OUTPUT_DIR` | _(未设置)_ | 调用省略 `output_dir` 时保存 PNG 的默认目录。默认为服务器的当前工作目录。 |
| `GEMINI_IMAGE_LOG_LEVEL` | `INFO` | 服务器的 stderr 日志级别（`DEBUG`/`INFO`/`WARNING`/`ERROR`）。 |
| `GEMINI_IMAGE_RETURN_MODE` | `file` | `file`（保存 + 路径，本地）· `inline`（图片字节）· `gcs`（上传 + 签名 URL — 适用于 Claude 应用）。 |
| `GEMINI_IMAGE_GCS_BUCKET` | _(未设置)_ | `gcs` 模式的私有存储桶。对象为 v4 签名（非公开）；配对生命周期删除规则。 |
| `GEMINI_IMAGE_GCS_TTL_DAYS` | `7` | `gcs` 模式的签名 URL 生命周期（天数）。 |
`output_dir` 解析顺序：**显式工具参数 → `GEMINI_IMAGE_OUTPUT_DIR` → 进程 CWD**。
## 模型
传递友好 **别名** — 绝不能使用原始模型 ID。
| 别名 | Vertex 模型 ID | 系列 | 可编辑？ | 位置 | 备注 |
|---|---|---|---|---|---|
| `nano-banana` | `gemini-2.5-flash-image` | gemini | 是 | `global` | **默认**。GA。文本 → 图片 + 编辑/融合。 |
| `nano-banana-pro` | `gemini-3-pro-image-preview` | gemini | 是 | `global` | Vertex 预览版；最多 14 个参考图片，最多 4K。可能 404 如果项目未被隔离。 |
| `imagen-4` | `imagen-4.0-generate-001` | imagen | 否 | `us-central1` | GA 标准。仅文本 → 图片。预计停用日期（~2026-06-30）。 |
| `imagen-4-fast` | `imagen-4.0-fast-generate-001` | imagen | 否 | `us-central1` | GA 快速/低成本。仅文本 → 图片。 |
| `imagen-4-ultra` | `imagen-4.0-ultra-generate-001` | imagen | 否 | `us-central1` | GA 最高质量。`n=1` 仅限。 |
Gemini 宽高比：`1:1, 2:3, 3:2, 3:4, 4:3, 4:5, 5:4, 9:16, 16:9, 21:9`。
Imagen 宽高比：`1:1, 3:4, 4:3, 9:16, 16:9`。
> Gemini 模型是持久路径。`imagen-4*` 别名是尽力而为：Imagen 4 有宣布的 EOL（~2026-06-30），在运行时可能会失败 — 原始 Vertex 错误原样呈现。
## 工具
- **`generate_image(prompt, model="nano-banana", aspect_ratio="1:1", n=1, output_dir=None, return_image=True)`**
文本 → 图片。对于 Gemini，`n>1` 循环每次调用一个图片；Imagen 使用原生批处理（`imagen-4-ultra` 限制为 1）。`n` 每次调用限制为 8 — 每个图片都是单独计费的生成。
- **`edit_image(image_paths, prompt, model="nano-banana", output_dir=None, return_image=True)`**
图片（们）+ 指令 → 图片。一个输入 = 编辑，两个或多个 = 融合。**仅限 Gemini 别名** — `imagen-4*` 被明确错误拒绝。
- **`list_models()`** — 别名表 + 备注（便宜，离线）。
## 注册到 Claude Code（从克隆）
[快速开始](#快速开始一步到位无需克隆) uvx 命令无需克隆。如果您已经克隆了仓库，请使用跟踪脚本 — 它自动派生仓库路径并从环境中读取您的项目。`~/.claude.json` **未** 被提交。
```bash
GOOGLE_CLOUD_PROJECT=您的GCP项目ID bash scripts/register.sh
```
等效原始命令：
```bash
claude mcp add gemini-image \
-e GOOGLE_CLOUD_PROJECT=您的GCP项目ID \
-e GOOGLE_CLOUD_LOCATION=global \
--scope user \
-- uv --directory /path/to/gemini-image-mcp run gemini-image-mcp
```
`--scope user` 放置在 **后** `-e` 标志和 **前** 名称（CLI 拒绝在 `-e` 后直接使用名称）。`-t stdio` 由 `-- <command>` 形式隐含。
## 远程部署（Cloud Run / AWS / 您的 VM）
在 **streamable-http** 上运行相同的服务器，以便 Claude 应用（网页 / 桌面 / **移动**）可以使用它作为自定义连接器并直接在聊天中生成图片。由于远程客户端无法读取服务器的磁盘，因此设置返回模式以发送图片： **`gcs`** 将每个图片上传到私有存储桶并返回 **签名 URL**（可靠的选择 — Claude 应用不渲染内联 MCP 图片块），或 `inline` 返回原始字节供客户端使用。下面的 Cloud Run 部署使用 `gcs`。
**身份验证现实：** claude.ai 自定义连接器不发送静态承载令牌，必须到达公共 URL。因此部署是 **公共** 的，由 **秘密路径** 保护：MCP 端点位于 `/<secret>/mcp`，整个 URL 是凭证。保持秘密；如果泄漏，请轮换（新秘密 + 重新部署）。
### 任意容器主机（Docker）
```bash
docker build -t gemini-image-mcp .
docker run -p 8080:8080 \
-e GOOGLE_CLOUD_PROJECT=您的GCP项目ID \
-e GEMINI_IMAGE_RETURN_MODE=inline \
-e MCP_PATH_SECRET="$(openssl rand -hex 24)" \
gemini-image-mcp
# 端点：http://localhost:8080/<secret>/mcp
```
在 AWS / 您的 VM 上，通过负载均衡器或反向代理提供 TLS（连接器需要 `https`），并通过平台的工作负载身份或服务帐户提供 ADC — 绝不能提交密钥文件。
### Google Cloud Run（脚本）
```bash
GOOGLE_CLOUD_PROJECT=您的GCP项目ID ./scripts/deploy_cloudrun.sh
```
脚本启用所需的 API，在 Secret Manager 中生成秘密路径令牌，授予 Cloud Run 运行时服务帐户 `roles/aiplatform.user`（通过 ADC 的 Vertex — 无密钥文件）以及秘密访问权限，从源代码构建并部署 **公共 + 缩放至零 + 最大 2 实例**。它打印 **连接器 URL**（`https://<service>/<secret>/mcp`）。在 Cloud Run 上，ADC 是服务帐户自动提供的。
### 将其添加为 Claude 连接器
1. claude.ai（或 Claude 桌面应用）→ **设置 → 连接器 → 添加自定义连接器**。
2. 粘贴 **连接器 URL**（`https://<service>/<secret>/mcp`）；将身份验证留为空。
3. **添加**，然后在聊天中询问 Claude **"生成一张 … 的图片"** — 它调用 `generate_image` 并返回一个可查看的签名 URL 链接到图片。在 **网页、桌面和移动设备** 上均可使用。
### 验证部署
```bash
uv run python scripts/smoke_remote.py "https://<service>/<secret>/mcp" # 列出工具
uv run python scripts/smoke_remote.py "https://<service>/<secret>/mcp" --generate "a red panda" # 一张图片
```
## 备注和注意事项
- **SynthID 水印：** 所有 Gemini 图片输出都带有不可见的 [SynthID](https://deepmind.google/technologies/synthid/) 水印。这是不可选的。
- **数据驻留：** `global` **不** 满足数据驻留要求，并且具有独立的配额，与区域端点不同。对于大多数个人/开发使用来说是足够的。
- **预览可能不会内联渲染** 在每个 Claude Code 版本中，并且可能很昂贵 — 这就是为什么完整的解析文件始终在磁盘上，并且始终返回路径。
- **stdio 与远程：** stdio 服务器（快速启动）针对 **Claude Code**（终端 + IDE），并且通过其自己的配置，针对 Claude 桌面应用。对于 **Claude 应用（网页/桌面/移动）** 和在聊天中生成图片，请部署 HTTP 服务器 — 请参阅 [远程部署](#远程部署-cloud-run--aws--您的-vm)。
## 许可证
[MIT](LICENSE)。
