# https://github.com/JimothySnicket/gemini-image-mcp 项目说明书
生成时间：2026-05-31 02:37:49 UTC
## 目录
- [项目介绍](#project-introduction)
- [快速入门](#quick-start)
- [系统架构](#system-architecture)
- [核心模块分析](#core-modules)
- [generate_image 工具详解](#generate-image-tool)
- [process_image 工具详解](#process-image-tool)
- [配置指南](#configuration-guide)
- [部署与客户端集成](#deployment-guide)
- [成本追踪与速率限制](#cost-tracking)
- [Gemini 模型对比](#gemini-models)
## 项目介绍
### 相关页面
相关主题：[快速入门](#quick-start), [系统架构](#system-architecture)
相关源码文件
以下源码文件用于生成本页说明：
- [README.md](https://github.com/JimothySnicket/gemini-image-mcp/blob/main/README.md)
- [package.json](https://github.com/JimothySnicket/gemini-image-mcp/blob/main/package.json)
- [CHANGELOG.md](https://github.com/JimothySnicket/gemini-image-mcp/blob/main/CHANGELOG.md)
- [CONTRIBUTING.md](https://github.com/JimothySnicket/gemini-image-mcp/blob/main/CONTRIBUTING.md)
- [server.json](https://github.com/JimothySnicket/gemini-image-mcp/blob/main/server.json)
- [src/index.ts](https://github.com/JimothySnicket/gemini-image-mcp/blob/main/src/index.ts)
- [src/generate.ts](https://github.com/JimothySnicket/gemini-image-mcp/blob/main/src/generate.ts)
- [skills/image-generation/SKILL.md](https://github.com/JimothySnicket/gemini-image-mcp/blob/main/skills/image-generation/SKILL.md)
# 项目介绍
## 项目概述
gemini-image-mcp 是一个基于 Google Gemini API 的模型上下文协议（Model Context Protocol，MCP）服务器，专门用于图像生成、编辑和本地图像处理。 资料来源：[README.md](https://github.com/JimothySnicket/gemini-image-mcp/blob/main/README.md)
该项目由 Jamie Donaldson 开发，采用 MIT 开源许可证发布。通过 MCP 协议，该工具可以与 Claude Code、Claude Desktop 等多种 AI 助手无缝集成，为用户提供强大的 AI 图像处理能力。 资料来源：[package.json](https://github.com/JimothySnicket/gemini-image-mcp/blob/main/package.json)
### 核心特性
| 特性 | 说明 |
|------|------|
| 文本生成图像 | 通过自然语言描述生成图像 |
| 图像编辑 | 基于参考图像进行 AI 驱动的编辑 |
| 多轮对话 | 支持迭代式图像优化会话 |
| 本地处理 | 免费、无 API 调用的本地图像处理 |
| 成本控制 | 支持请求频率和费用限制 |
| 多模型支持 | 自动发现并支持多种 Gemini 图像模型 |
## 技术架构
### 技术栈
项目采用现代 TypeScript 技术栈构建，主要依赖包括：
| 依赖 | 版本 | 用途 |
|------|------|------|
| `@google/genai` | ^1.44.0 | Google Gemini API 官方 SDK |
| `@modelcontextprotocol/sdk` | ^1.22.0 | MCP 协议实现 |
| `sharp` | ^0.34.5 | 高性能图像处理库 |
| `zod` | ^3.24.0 | TypeScript Schema 验证 |
资料来源：[package.json](https://github.com/JimothySnicket/gemini-image-mcp/blob/main/package.json)
### 模块组成
项目源代码位于 `src/` 目录下，核心模块包括：
```mermaid
graph TD
A[src/index.ts] --> B[MCP Server 入口]
A --> C[工具注册]
A --> D[请求处理]
B --> E[config.ts]
E --> F[配置加载与验证]
C --> G[generate_image]
C --> H[process_image]
G --> I[generate.ts]
I --> J[Gemini API 调用]
I --> K[模型自动发现]
I --> L[会话管理]
H --> M[process.ts]
M --> N[Sharp 图像处理]
M --> O[背景移除]
M --> P[裁剪与缩放]
```
### 系统架构图
```mermaid
graph LR
A[MCP 客户端] -->|STDIO 通信| B[gemini-image-mcp Server]
B -->|API 调用| C[Google Gemini API]
C -->|图像数据| B
B -->|本地处理| D[Sharp 引擎]
D -->|处理结果| B
B -->|文件系统| E[输出目录]
```
## 核心功能详解
### 工具一：generate_image
`generate_image` 是一个 AI 驱动的图像生成和编辑工具，通过 Google Gemini API 实现。 资料来源：[README.md](https://github.com/JimothySnicket/gemini-image-mcp/blob/main/README.md)
#### 支持的图像模型
| 模型 | 特点 | 分辨率支持 | 备注 |
|------|------|-----------|------|
| `gemini-2.5-flash-image` | 快速、廉价 | 1K | 默认模型，2026年10月停用 |
| `gemini-3-pro-image-preview` | 最佳质量、文字渲染 | 1K、2K、4K | 最多支持14张参考图像 |
| `gemini-3.1-flash-image-preview` | 速度与质量平衡 | 512、1K、2K、4K | 支持 Google Search 接地 |
资料来源：[README.md](https://github.com/JimothySnicket/gemini-image-mcp/blob/main/README.md)
#### 输入参数
| 参数 | 必填 | 类型 | 说明 |
|------|------|------|------|
| `prompt` | 是 | string | 图像描述或编辑指令 |
| `images` | 否 | string[] | 输入/参考图像路径数组 |
| `model` | 否 | string | Gemini 模型 ID |
| `aspectRatio` | 否 | string | 宽高比：1:1、16:9、9:16、3:2、2:3、4:3、3:4、21:9 |
| `resolution` | 否 | string | 分辨率：1K、2K、4K |
| `outputDir` | 否 | string | 输出目录覆盖 |
| `filename` | 否 | string | 文件基础名称（自动版本控制） |
| `subfolder` | 否 | string | 输出子文件夹 |
| `sessionId` | 否 | string | 继续多轮编辑会话 |
| `seed` | 否 | integer | 随机种子（可复现生成） |
| `useSearchGrounding` | 否 | boolean | 启用 Google Search 接地 |
资料来源：[README.md](https://github.com/JimothySnicket/gemini-image-mcp/blob/main/README.md)
#### 使用场景
**文本生成图像：**
```json
{
"prompt": "A modern dashboard UI with dark theme and blue accent colours",
"aspectRatio": "16:9",
"resolution": "2K",
"filename": "dashboard-hero"
}
```
**图像编辑（多轮对话）：**
```json
{
"prompt": "Change the background to a sunset over water",
"images": ["./src/assets/hero.png"],
"sessionId": "session-1711929600000-a1b2c3"
}
```
### 工具二：process_image
`process_image` 是一个本地图像处理工具，使用 Sharp 库实现，完全免费且无需 API 调用。 资料来源：[README.md](https://github.com/JimothySnicket/gemini-image-mcp/blob/main/README.md)
#### 功能列表
| 功能 | 说明 |
|------|------|
| 裁剪 | 精确像素裁剪、按宽高比裁剪、焦点裁剪（注意力/熵策略） |
| 缩放 | 按宽度、高度或两者缩放（保持宽高比） |
| 背景移除 | 阈值法（白色背景）或色度键控（绿幕/纯色） |
| 边缘羽化 | HSV 色度键控 + smoothstep 羽化 + 边缘抗锯齿 |
| 修边 | 自动移除白边/透明边 |
| 格式转换 | PNG、JPEG、WebP 及质量控制 |
#### 输入参数
| 参数 | 必填 | 类型 | 说明 |
|------|------|------|------|
| `imagePath` | 是 | string | 待处理图像路径 |
| `crop` | 否 | object | 裁剪配置 |
| `resize` | 否 | object | 缩放配置 |
| `removeBackground` | 否 | object | 背景移除配置 |
| `trim` | 否 | boolean | 是否自动修边 |
| `format` | 否 | string | 输出格式：png、jpeg、webp |
| `quality` | 否 | number | JPEG/WebP 质量 1-100 |
| `filename` | 否 | string | 输出文件名 |
| `subfolder` | 否 | string | 输出子文件夹 |
| `outputDir` | 否 | string | 输出目录覆盖 |
资料来源：[README.md](https://github.com/JimothySnicket/gemini-image-mcp/blob/main/README.md)
#### 典型工作流
```mermaid
graph LR
A[生成图像] --> B{主体颜色}
B -->|红色/蓝色/黑色| C[绿幕生成]
B -->|黄色/绿色/玻璃| D[画布方法]
C --> E[色度键处理]
E --> F[修边]
F --> G[完成]
D --> H[添加主体到背景]
H --> G
```
## 配置管理
### 配置优先级
项目支持多层配置，按优先级从高到低排列：
```mermaid
graph TD
A[环境变量] -->|最高| B[本地配置]
B --> C[全局配置]
C -->|最低| D[默认值]
```
优先级顺序：环境变量 > 本地配置（`.gemini-image-mcp.json`） > 全局配置（`~/.gemini-image-mcp.json`） > 默认值。 资料来源：[README.md](https://github.com/JimothySnicket/gemini-image-mcp/blob/main/README.md)
### 环境变量
| 变量 | 说明 | 默认值 |
|------|------|--------|
| `GEMINI_API_KEY` | Google Gemini API 密钥 | — |
| `MAX_REQUESTS_PER_HOUR` | 每小时最大请求数 | 无限制 |
| `MAX_COST_PER_HOUR` | 每小时最大费用（美元） | 无限制 |
| `OUTPUT_DIR` | 输出目录 | ~/gemini-images |
| `DEFAULT_MODEL` | 默认模型 | gemini-2.5-flash-image |
| `LOG_LEVEL` | 日志级别 | info |
| `REQUEST_TIMEOUT_MS` | 请求超时（毫秒） | 60000 |
资料来源：[README.md](https://github.com/JimothySnicket/gemini-image-mcp/blob/main/README.md)
### 配置文件格式
使用 `--init` 参数可生成带注释的配置文件模板：
```bash
npx @jimothy-snicket/gemini-image-mcp --init
```
配置文件示例（JSONC 格式，支持注释）：
```jsonc
{
"defaultModel": "gemini-3.1-flash-image-preview",
"defaults": {
"generate": {
"aspectRatio": "16:9",
"resolution": "2K"
},
"process": {
"removeBackground": { "color": "#00FF00" },
"trim": true
}
}
}
```
### 安全特性
项目在配置管理中实现了多项安全措施：
| 安全特性 | 说明 |
|----------|------|
| API 密钥验证 | 配置文件中的 API 密钥会被警告拒绝（配置文件可能提交到仓库） |
| JSONC 解析 | 智能字符串感知解析，不会错误处理 URL 中的斜杠 |
| 原型污染防护 | 配置合并时检查 `__proto__`、`constructor`、`prototype` |
| 未知键警告 | 配置文件中的未知键会被警告并丢弃 |
资料来源：[CHANGELOG.md](https://github.com/JimothySnicket/gemini-image-mcp/blob/main/CHANGELOG.md)
## 安装与部署
### 前置条件
| 依赖 | 版本要求 |
|------|----------|
| Node.js | >= 18.0.0 |
| npm / bun | 推荐使用 bun 以获得更好的开发体验 |
### 安装步骤
**使用 npm 安装：**
```bash
npm install -g @jimothy-snicket/gemini-image-mcp
```
**本地开发安装：**
```bash
git clone https://github.com/JimothySnicket/gemini-image-mcp.git
cd gemini-image-mcp
bun install
bun run build
```
### API 密钥配置
**Windows (PowerShell)：**
```powershell
[System.Environment]::SetEnvironmentVariable('GEMINI_API_KEY', 'your-key-here', 'User')
```
**macOS / Linux：**
```bash
echo 'export GEMINI_API_KEY="your-key-here"' >> ~/.bashrc
source ~/.bashrc
```
### MCP 客户端连接
项目支持多种 MCP 客户端连接方式：
```mermaid
graph TD
A[gemini-image-mcp] --> B{Claude Code}
A --> C{Claude Desktop}
A --> D{其他 MCP 客户端}
B --> E[plugin.json + SKILL.md]
C --> F[配置 JSON]
D --> G[标准 MCP STDIO]
```
#### Claude Code 集成
Claude Code 可通过插件层直接使用本项目的技能（Skill）。相关配置文件位于仓库根目录：
- `plugin.json` — 插件清单
- `skills/image-generation/SKILL.md` — 技能使用说明
#### Claude Desktop 配置
在 `claude_desktop_config.json` 中添加：
```json
{
"mcpServers": {
"gemini-image": {
"command": "npx",
"args": ["@jimothy-snicket/gemini-image-mcp"]
}
}
}
```
资料来源：[README.md](https://github.com/JimothySnicket/gemini-image-mcp/blob/main/README.md)
## 开发指南
### 本地开发
```bash
bun install # 安装依赖
bun run dev # 直接运行源代码
bun run build # 编译 TypeScript 到 dist/
```
### 测试
运行测试需要设置 `GEMINI_API_KEY` 环境变量以测试实际的 Gemini API 调用。 资料来源：[CONTRIBUTING.md](https://github.com/JimothySnicket/gemini-image-mcp/blob/main/CONTRIBUTING.md)
### 贡献指南
1. **先开 Issue**：在编写代码之前，先描述 bug 或功能需求
2. **单一职责**：每个 PR 只做一件事，不要捆绑不相关的更改
3. **构建检查**：确保 `bun run build` 无错误通过
4. **手动测试**：使用实际 Gemini API 测试更改
5. **保持精简**：发现其他需要修复的问题时，单独开 Issue
## 版本历史
| 版本 | 发布日期 | 主要更新 |
|------|----------|----------|
| 0.4.0 | 2026-05 | 集中化配置管理、32项配置模块测试、安全增强 |
| 0.3.0 | 2026-04 | `process_image` 工具、会话跟踪、生成清单 |
| 0.2.0 | 2026-04 | 本地图像处理、色度键、裁剪、格式转换 |
| 0.1.0 | 2026-01 | 初始版本、基础图像生成 |
资料来源：[CHANGELOG.md](https://github.com/JimothySnicket/gemini-image-mcp/blob/main/CHANGELOG.md)
## 许可证
本项目采用 MIT 许可证开源。 资料来源：[README.md](https://github.com/JimothySnicket/gemini-image-mcp/blob/main/README.md)
---
## 快速入门
### 相关页面
相关主题：[项目介绍](#project-introduction), [部署与客户端集成](#deployment-guide), [generate_image 工具详解](#generate-image-tool)
相关源码文件
以下源码文件用于生成本页说明：
- [README.md](https://github.com/JimothySnicket/gemini-image-mcp/blob/main/README.md)
- [package.json](https://github.com/JimothySnicket/gemini-image-mcp/blob/main/package.json)
- [src/index.ts](https://github.com/JimothySnicket/gemini-image-mcp/blob/main/src/index.ts)
- [src/generate.ts](https://github.com/JimothySnicket/gemini-image-mcp/blob/main/src/generate.ts)
- [CHANGELOG.md](https://github.com/JimothySnicket/gemini-image-mcp/blob/main/CHANGELOG.md)
- [CONTRIBUTING.md](https://github.com/JimothySnicket/gemini-image-mcp/blob/main/CONTRIBUTING.md)
# 快速入门
本文档帮助你在 5 分钟内完成 `gemini-image-mcp` 的安装、配置和首次图像生成。
## 系统概述
`gemini-image-mcp` 是一个基于 Model Context Protocol (MCP) 的服务器，为 Google Gemini 提供图像生成和本地处理能力。核心提供两个工具：
| 工具名称 | 用途 | 成本 |
|---------|------|------|
| `generate_image` | AI 驱动的图像生成与编辑 | 消耗 Gemini API 配额（约 $0.04-0.15/张） |
| `process_image` | 本地图像处理（裁剪、缩放、去背景） | 免费，无需 API 调用 |
资料来源：[README.md](https://github.com/JimothySnicket/gemini-image-mcp/blob/main/README.md)
## 快速安装
### 前置要求
- **Node.js**: >= 18.0.0
- **包管理器**: npm、yarn 或 bun
- **Gemini API 密钥**: 从 [Google AI Studio](https://aistudio.google.com/apikey) 获取
资料来源：[package.json:22](https://github.com/JimothySnicket/gemini-image-mcp/blob/main/package.json)
### 安装命令
```bash
# 通过 npm 全局安装
npm install -g @jimothy-snicket/gemini-image-mcp
# 或使用 npx 直接运行（无需全局安装）
npx @jimothy-snicket/gemini-image-mcp
```
## 配置 API 密钥
服务器通过 `GEMINI_API_KEY` 环境变量读取你的密钥。
### Windows (PowerShell)
```powershell
[System.Environment]::SetEnvironmentVariable('GEMINI_API_KEY', 'your-key-here', 'User')
```
重启终端后生效。
资料来源：[README.md](https://github.com/JimothySnicket/gemini-image-mcp/blob/main/README.md)
### macOS / Linux
```bash
echo 'export GEMINI_API_KEY="your-key-here"' >> ~/.bashrc
source ~/.bashrc # 或 source ~/.zshrc (zsh 用户)
```
### 验证配置
```bash
echo $GEMINI_API_KEY
```
如果输出你的密钥字符串，说明配置成功。
## 配置文件（可选）
除了环境变量，你还可以使用 JSON 配置文件进行更细粒度的控制：
```bash
npx @jimothy-snicket/gemini-image-mcp --init
```
此命令在 `~/.gemini-image-mcp.json` 创建默认配置文件。
### 配置优先级
```
环境变量 > 本地配置文件 > 全局配置文件 > 默认值
```
资料来源：[README.md](https://github.com/JimothySnicket/gemini-image-mcp/blob/main/README.md)
### 配置文件示例
```json
{
"defaultModel": "gemini-3.1-flash-image-preview",
"defaults": {
"generate": {
"aspectRatio": "16:9",
"resolution": "2K"
},
"process": {
"removeBackground": { "color": "#00FF00" },
"trim": true
}
}
}
```
## 连接到 MCP 客户端
### Claude Code
Claude Code 原生支持 MCP 服务器。安装后直接询问图像相关任务即可：
```
用户：帮我生成一个产品海报
```
资料来源：[README.md](https://github.com/JimothySnicket/gemini-image-mcp/blob/main/README.md)
### Claude Desktop
编辑配置文件：
**macOS/Linux:**
```bash
~/.claude/desktops.json
```
**Windows:**
```bash
%APPDATA%\claude\desktops.json
```
配置内容：
```json
{
"mcpServers": {
"gemini-image": {
"command": "npx",
"args": ["@jimothy-snicket/gemini-image-mcp"]
}
}
}
```
### 通用 MCP 客户端
```json
{
"mcpServers": {
"gemini-image": {
"command": "npx",
"args": ["@jimothy-snicket/gemini-image-mcp"],
"env": {
"GEMINI_API_KEY": "your-api-key-here"
}
}
}
}
```
## 核心工具使用
### generate_image — AI 图像生成
#### 参数说明
| 参数 | 必填 | 说明 |
|------|------|------|
| `prompt` | 是 | 图像描述或编辑指令 |
| `images` | 否 | 输入/参考图像路径数组 |
| `model` | 否 | Gemini 模型 ID |
| `aspectRatio` | 否 | 宽高比：`1:1`, `16:9`, `9:16`, `3:2`, `2:3`, `4:3`, `3:4`, `21:9` |
| `resolution` | 否 | 分辨率：`1K`, `2K`, `4K` |
| `outputDir` | 否 | 输出目录覆盖 |
| `filename` | 否 | 保存文件名，自动版本化 |
| `subfolder` | 否 | 输出子目录 |
| `sessionId` | 否 | 多轮编辑会话 ID |
| `seed` | 否 | 整数种子，用于可复现生成 |
| `useSearchGrounding` | 否 | 启用 Google 搜索接地（仅 gemini-3.1-flash） |
资料来源：[src/index.ts](https://github.com/JimothySnicket/gemini-image-mcp/blob/main/src/index.ts)
#### 可用模型
| 模型 | 特点 | 分辨率 | 成本 |
|------|------|--------|------|
| `gemini-2.5-flash-image` | 快速、便宜（默认） | 1K | ~$0.04/张 |
| `gemini-3-pro-image-preview` | 最高质量、文本渲染 | 1K, 2K, 4K | ~$0.15/张 |
| `gemini-3.1-flash-image-preview` | 速度与质量平衡 | 512, 1K, 2K, 4K | 中等 |
资料来源：[README.md](https://github.com/JimothySnicket/gemini-image-mcp/blob/main/README.md)
#### 使用示例
**文本生成：**
```json
{
"prompt": "A modern dashboard UI with dark theme and blue accent colours",
"aspectRatio": "16:9",
"resolution": "2K",
"filename": "dashboard-hero",
"subfolder": "landing-page"
}
```
**图像编辑：**
```json
{
"prompt": "Change the background to a sunset over water",
"images": ["./src/assets/hero.png"],
"aspectRatio": "16:9"
}
```
### process_image — 本地图像处理
#### 参数说明
| 参数 | 必填 | 说明 |
|------|------|------|
| `imagePath` | 是 | 待处理图像路径 |
| `crop` | 否 | 裁剪参数（像素、宽高比、焦点策略） |
| `resize` | 否 | 缩放尺寸（保持宽高比） |
| `removeBackground` | 否 | 背景去除（阈值或色度键） |
| `trim` | 否 | 自动去除白边/透明边 |
| `format` | 否 | 输出格式：`png`, `jpeg`, `webp` |
| `quality` | 否 | 质量 1-100（JPEG/WebP） |
| `outputDir` | 否 | 输出目录 |
| `filename` | 否 | 保存文件名 |
| `subfolder` | 否 | 输出子目录 |
资料来源：[src/index.ts](https://github.com/JimothySnicket/gemini-image-mcp/blob/main/src/index.ts)
#### 使用示例
**去除白色背景：**
```json
{
"imagePath": "./product.png",
"removeBackground": {"threshold": 230},
"trim": true,
"filename": "product-transparent"
}
```
**绿幕抠像（两步流程）：**
```json
// 步骤1：生成绿幕图像
{"prompt": "A product photo on a bright green background", "filename": "product-green"}
// 步骤2：本地去背景
{
"imagePath": "./product-green.png",
"removeBackground": {"color": "#00FF00"},
"trim": true,
"filename": "product-transparent"
}
```
**焦点裁剪：**
```json
{
"imagePath": "./photo.png",
"crop": {"aspectRatio": "16:9", "strategy": "attention"},
"filename": "hero-banner"
}
```
## 工作流程图
```mermaid
graph TD
A[用户请求] --> B{选择工具}
B -->|generate_image| C[AI 图像生成]
B -->|process_image| D[本地图像处理]
C --> E{多轮编辑?}
E -->|是| F[使用 sessionId 继续]
E -->|否| G[单次生成]
F --> G
G --> H[保存到 outputDir]
D --> H
H --> I[返回 imagePath]
style C fill:#e1f5fe
style D fill:#f3e5f5
```
## 成本控制与速率限制
### 环境变量配置
```bash
# 每小时最大请求数
export MAX_REQUESTS_PER_HOUR=20
# 每小时最大成本（美元）
export MAX_COST_PER_HOUR=5
```
### 安全特性
- API 密钥不接受配置文件（防止意外提交）
- 配置深度合并时防护原型污染攻击
- 未知配置项会警告并丢弃
资料来源：[CHANGELOG.md](https://github.com/JimothySnicket/gemini-image-mcp/blob/main/CHANGELOG.md)
## 输出管理
### 文件命名
- 指定文件名时自动添加扩展名
- 文件名冲突时自动版本化：`hero.png` → `hero-v2.png` → `hero-v3.png`
### 子目录组织
```json
{
"filename": "hero",
"subfolder": "landing-page"
}
```
输出路径：`~/gemini-images/landing-page/hero.png`
### 生成日志
每次生成自动追加到 `generations.jsonl`，记录：
- 提示词
- 参数
- 模型
- 成本
- 输出路径
资料来源：[CHANGELOG.md](https://github.com/JimothySnicket/gemini-image-mcp/blob/main/CHANGELOG.md)
## 开发与调试
### 本地开发
```bash
# 安装依赖
bun install # 或 npm install
# TypeScript 编译
bun run build
# 直接运行源码
bun run dev
```
资料来源：[CONTRIBUTING.md](https://github.com/JimothySnicket/gemini-image-mcp/blob/main/CONTRIBUTING.md)
### 测试
测试图像生成需要设置 `GEMINI_API_KEY` 环境变量，详见 README。
## 故障排除
| 问题 | 解决方案 |
|------|---------|
| `Failed to list models` | 检查 API 密钥是否正确 |
| 图像生成被阻止 | 返回 `raiFilteredReason`，内容违反安全政策 |
| 文件格式错误 | 确保输入格式为 PNG、JPEG、GIF、WebP 或 BMP |
| 分辨率不支持 | gemini-2.5-flash 仅支持 1K |
资料来源：[src/generate.ts](https://github.com/JimothySnicket/gemini-image-mcp/blob/main/src/generate.ts)
## 下一步
- 查看 [SKILL.md](https://github.com/JimothySnicket/gemini-image-mcp/blob/main/skills/image-generation/SKILL.md) 了解高级提示技巧
- 阅读完整 [README.md](https://github.com/JimothySnicket/gemini-image-mcp/blob/main/README.md) 获取详细功能说明
- 查看 [CHANGELOG.md](https://github.com/JimothySnicket/gemini-image-mcp/blob/main/CHANGELOG.md) 了解版本历史
---
## 系统架构
### 相关页面
相关主题：[项目介绍](#project-introduction), [核心模块分析](#core-modules)
相关源码文件
以下源码文件用于生成本页说明：
- [src/index.ts](https://github.com/JimothySnicket/gemini-image-mcp/blob/main/src/index.ts)
- [src/generate.ts](https://github.com/JimothySnicket/gemini-image-mcp/blob/main/src/generate.ts)
- [package.json](https://github.com/JimothySnicket/gemini-image-mcp/blob/main/package.json)
- [server.json](https://github.com/JimothySnicket/gemini-image-mcp/blob/main/server.json)
- [README.md](https://github.com/JimothySnicket/gemini-image-mcp/blob/main/README.md)
# 系统架构
## 概述
gemini-image-mcp 是一个基于 Model Context Protocol (MCP) 的服务器实现，为 Google Gemini 图像生成与编辑功能提供标准化的工具接口。该项目使 AI 助手能够通过 MCP 协议调用 Gemini API 实现文本生成图像、图像编辑以及本地图像处理功能。
项目核心目标包括：
- 提供 `generate_image` 工具实现 AI 驱动的图像生成与编辑
- 提供 `process_image` 工具实现本地图像处理（无需 API 调用）
- 支持多轮会话编辑、速率限制、成本追踪
- 统一的配置管理系统
资料来源：[README.md:1-20]()
## 架构分层
```
┌─────────────────────────────────────────────────────────────┐
│ MCP 客户端层 │
│ (Claude Code / Claude Desktop / 其他 MCP 客户端) │
└─────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ MCP 服务器层 (src/index.ts) │
│ ┌─────────────────┐ ┌─────────────────┐ │
│ │ generate_image │ │ process_image │ │
│ │ 工具定义 │ │ 工具定义 │ │
│ └────────┬────────┘ └────────┬────────┘ │
└──────────────────────────┬───────────┬─────────────────────┘
│ │
▼ ▼
┌─────────────────────────────────────────────────────────────┐
│ 业务逻辑层 │
│ ┌──────────────────┐ ┌──────────────────┐ │
│ │ generate.ts │ │ process.ts │ │
│ │ 图像生成与编辑 │ │ 本地图像处理 │ │
│ └────────┬─────────┘ └────────┬─────────┘ │
└─────────────┼─────────────────────────┼─────────────────────┘
│ │
▼ ▼
┌─────────────────────────────────────────────────────────────┐
│ 外部依赖层 │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────────┐ │
│ │@google/genai│ │ sharp │ │@modelcontextpro│ │
│ │ Gemini │ │ 本地图像处理 │ │ tocol/sdk │ │
│ └─────────────┘ └─────────────┘ └─────────────────┘ │
└─────────────────────────────────────────────────────────────┘
```
资料来源：[package.json:16-32]()
## 核心依赖
| 依赖包 | 版本 | 作用 |
|--------|------|------|
| `@google/genai` | ^1.44.0 | Google Gemini API 客户端 |
| `@modelcontextprotocol/sdk` | ^1.22.0 | MCP 协议实现 |
| `sharp` | ^0.34.5 | 高性能本地图像处理 |
| `zod` | ^3.24.0 | 参数验证与类型安全 |
| `typescript` | ^6.0.3 | 类型检查与编译 |
| `@types/node` | ^25.6.0 | Node.js 类型定义 |
资料来源：[package.json:16-32]()
## MCP 工具接口
### 工具注册架构
MCP 服务器通过 `@modelcontextprotocol/sdk` 定义并注册工具。每个工具包含参数模式（基于 Zod schema）和异步处理函数。
```mermaid
graph TD
A[MCP 服务器初始化] --> B[注册工具清单]
B --> C[generate_image]
B --> D[process_image]
C --> E[客户端调用请求]
D --> E
E --> F[参数验证 Zod Schema]
F --> G{验证结果}
G -->|通过| H[执行业务逻辑]
G -->|失败| I[返回错误]
H --> J[返回 JSON 结果]
```
资料来源：[src/index.ts:1-50]()
### generate_image 工具
`generate_image` 是核心的 AI 图像生成工具，支持文本生成图像和多轮编辑会话。
**参数模型：**
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `prompt` | string | 是 | 图像描述或编辑指令 |
| `images` | string[] | 否 | 参考图像文件路径数组 |
| `model` | string | 否 | Gemini 模型 ID |
| `aspectRatio` | string | 否 | 宽高比 (1:1, 16:9, 9:16, 3:2, 2:3, 4:3, 3:4, 21:9) |
| `resolution` | string | 否 | 分辨率 (1K, 2K, 4K) |
| `outputDir` | string | 否 | 输出目录覆盖 |
| `filename` | string | 否 | 保存文件名 |
| `subfolder` | string | 否 | 输出子文件夹 |
| `sessionId` | string | 否 | 多轮会话 ID |
| `seed` | number | 否 | 随机种子（整数） |
| `useSearchGrounding` | boolean | 否 | 启用 Google Search 锚定 |
资料来源：[src/index.ts:80-150]()
### process_image 工具
`process_image` 提供本地图像处理功能，完全免费且无需 API 调用。
**参数模型：**
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `imagePath` | string | 是 | 源图像路径 |
| `crop` | object | 否 | 裁剪配置（像素/宽高比/焦点） |
| `resize` | object | 否 | 缩放配置（宽/高/保持比例） |
| `removeBackground` | object | 否 | 背景移除配置 |
| `trim` | boolean | 否 | 自动裁剪白边/透明边 |
| `format` | string | 否 | 输出格式 (png/jpeg/webp) |
| `quality` | number | 否 | 输出质量 1-100 |
| `outputDir` | string | 否 | 输出目录 |
| `filename` | string | 否 | 保存文件名 |
| `subfolder` | string | 否 | 输出子文件夹 |
资料来源：[src/index.ts:200-280]()
## 图像生成流程
### 完整生成流程
```mermaid
sequenceDiagram
participant Client as MCP 客户端
participant Server as MCP 服务器
participant Config as 配置系统
participant Gemini as Gemini API
participant Storage as 文件系统
Client->>Server: generate_image(prompt, images, model)
Server->>Config: loadConfig()
Config-->>Server: 配置对象
Server->>Server: 速率限制检查
Server->>Server: 验证模型可用性
Server->>Server: 读取输入图像为 base64
Server->>Gemini: 发送生成请求
Gemini-->>Server: 图像响应
Server->>Server: 检测 mimeType
Server->>Server: 解析输出路径
Server->>Storage: 保存图像文件
Server->>Storage: 记录到 generations.jsonl
Server-->>Client: 返回结果含 usage/session
```
资料来源：[src/generate.ts:1-100]()
### 模型发现机制
```mermaid
graph TD
A[启动时模型发现] --> B[调用 Gemini ListModels API]
B --> C{请求成功?}
C -->|是| D[遍历模型列表]
C -->|否| E[抛出错误: API key 无效?]
D --> F{匹配图像能力?}
F -->|是| G{排除 Imagen 模型?}
G -->|是| H[跳过]
G -->|否| I[添加到可用模型]
F -->|否| H
I --> J[缓存结果]
J --> K[返回可用模型列表]
```
项目支持的模型：
| 模型 | 特点 | 分辨率 | 参考图像数 |
|------|------|--------|-----------|
| gemini-2.5-flash-image | 快速、低成本 | 1K | 1 |
| gemini-3-pro-image-preview | 最佳质量、文本渲染 | 1K, 2K, 4K | 最多 14 张 |
| gemini-3.1-flash-image-preview | 速度与质量平衡 | 512, 1K, 2K, 4K | 支持 Search 锚定 |
资料来源：[src/generate.ts:50-80]()
## 配置系统
### 配置加载优先级
```mermaid
graph LR
A[环境变量] -->|最高| Z[最终配置]
B[本地配置
.gemini-image-mcp.json] -->|次高| Z
C[全局配置
~/.gemini-image-mcp.json] -->|次低| Z
D[代码默认值] -->|最低| Z
```
配置项说明：
| 配置项 | 类型 | 默认值 | 说明 |
|--------|------|--------|------|
| `GEMINI_API_KEY` | string | - | Google Gemini API 密钥 |
| `OUTPUT_DIR` | string | ~/gemini-images | 默认输出目录 |
| `DEFAULT_MODEL` | string | gemini-2.5-flash-image | 默认生成模型 |
| `LOG_LEVEL` | string | info | 日志级别 |
| `REQUEST_TIMEOUT_MS` | number | 60000 | 请求超时（毫秒） |
| `MAX_REQUESTS_PER_HOUR` | number | - | 每小时最大请求数 |
| `MAX_COST_PER_HOUR` | number | - | 每小时最大成本（美元） |
资料来源：[src/index.ts:300-350]()
### 配置文件格式
```jsonc
{
// 默认模型
"defaultModel": "gemini-3.1-flash-image-preview",
// 各工具默认参数
"defaults": {
"generate": {
"aspectRatio": "16:9",
"resolution": "2K"
},
"process": {
"removeBackground": { "color": "#00FF00" },
"trim": true
}
}
}
```
资料来源：[README.md:100-120]()
## 数据模型
### 图像生成响应
```typescript
interface GenerateResult {
imagePath: string; // 保存路径
mimeType: string; // 图像 MIME 类型
model: string; // 使用的模型
sessionId: string; // 会话 ID
sessionTurn: number; // 会话轮次
usage: {
promptTokens: number;
outputTokens: number;
imageTokens: number;
thinkingTokens: number;
totalTokens: number;
};
session: {
totalGenerations: number;
totalCost: number;
requestCount: number;
};
}
```
资料来源：[src/index.ts:150-180]()
### 图像处理管道
```mermaid
graph LR
A[输入图像] --> B[removeBackground]
B --> C[trim]
C --> D[crop]
D --> E[resize]
E --> F[format]
F --> G[输出图像]
H[quality 控制] -.-> F
```
处理操作支持链式调用，可在单次调用中完成背景移除、裁剪、缩放、格式转换等操作。
## 会话管理
### 多轮编辑架构
```mermaid
graph TD
A[首次调用] -->|无 sessionId| B[创建新会话]
B --> C[生成初始图像]
C --> D[返回 sessionId]
D --> E[客户端保存 sessionId]
E --> F[后续调用]
F -->|携带 sessionId| G[恢复会话历史]
G --> H[追加上下文]
H --> I[生成迭代图像]
I --> J[sessionTurn++]
```
会话特性：
- 会话 ID 基于时间戳和随机字符串生成
- 保留对话历史以实现更好的编辑效果
- 会话默认 30 分钟过期
- 模型不匹配时返回错误
资料来源：[src/generate.ts:150-200]()
## 速率限制
### 限制机制
```mermaid
graph TD
A[请求进入] --> B{检查速率限制}
B -->|MAX_REQUESTS_PER_HOUR| C{请求计数 < 限制?}
B -->|MAX_COST_PER_HOUR| D{累计成本 < 限制?}
C -->|是| E[放行]
C -->|否| F[拒绝请求]
D -->|是| E
D -->|否| F
F --> G[返回错误含剩余预算]
E --> H[执行业务逻辑]
```
速率限制可防止 AI 代理在循环中过度消耗资源。
## 项目入口点
| 文件 | 作用 |
|------|------|
| `src/index.ts` | MCP 服务器主入口，定义工具、处理请求 |
| `package.json` | 项目元数据，定义构建脚本和依赖 |
| `dist/index.js` | TypeScript 编译输出（生产环境使用） |
**启动方式：**
```bash
# 开发模式（使用 Bun）
bun run dev # bun run src/index.ts
# 生产模式
bun run build # TypeScript -> dist/
node dist/index.js
```
资料来源：[package.json:38-44]()
## 服务器配置
MCP 服务器通过 `server.json` 声明其元数据：
```json
{
"name": "io.github.JimothySnicket/gemini-image",
"description": "Google Gemini image generation, editing, and local processing via MCP",
"version": "0.4.0",
"packages": [{
"identifier": "@jimothy-snicket/gemini-image-mcp",
"transport": { "type": "stdio" },
"environmentVariables": [{
"name": "GEMINI_API_KEY",
"isRequired": true,
"isSecret": true
}]
}]
}
```
资料来源：[server.json:1-25]()
## 安全性特性
配置系统实现的安全措施：
| 安全措施 | 说明 |
|----------|------|
| API 密钥拒绝 | 配置文件中的 API 密钥会被拒绝并警告（防止提交到仓库） |
| JSONC 注释处理 | 字符串内的 URL 不会被误解析 |
| 原型污染防护 | deepMerge 时排除 `__proto__`、`constructor`、`prototype` |
| 未知配置警告 | 未知配置键会被警告并丢弃 |
资料来源：[CHANGELOG.md:10-25]()
## 总结
gemini-image-mcp 采用清晰的分层架构：
1. **协议层**：基于 MCP SDK 实现标准化工具接口
2. **工具层**：定义 `generate_image` 和 `process_image` 两个核心工具
3. **业务层**：封装图像生成和处理的业务逻辑
4. **集成层**：通过 `@google/genai` 连接 Gemini API，通过 `sharp` 实现本地处理
5. **配置层**：统一的配置加载系统，支持多优先级配置源
该架构使项目能够灵活支持多种 MCP 客户端，同时保持核心逻辑的独立性和可测试性。
---
## 核心模块分析
### 相关页面
相关主题：[系统架构](#system-architecture), [配置指南](#configuration-guide)
相关源码文件
以下源码文件用于生成本页说明：
- [src/config.ts](https://github.com/JimothySnicket/gemini-image-mcp/blob/main/src/config.ts)
- [src/generate.ts](https://github.com/JimothySnicket/gemini-image-mcp/blob/main/src/generate.ts)
- [src/process.ts](https://github.com/JimothySnicket/gemini-image-mcp/blob/main/src/process.ts)
- [src/tracker.ts](https://github.com/JimothySnicket/gemini-image-mcp/blob/main/src/tracker.ts)
- [src/pricing.ts](https://github.com/JimothySnicket/gemini-image-mcp/blob/main/src/pricing.ts)
- [src/utils.ts](https://github.com/JimothySnicket/gemini-image-mcp/blob/main/src/utils.ts)
# 核心模块分析
## 概述
gemini-image-mcp 是一个基于 Google Gemini API 的 MCP（Model Context Protocol）服务器，专门用于图像生成、编辑和本地处理。该项目采用 TypeScript 开发，支持双工具架构：AI 驱动的 `generate_image` 和本地免费的 `process_image`。
项目核心模块包括配置管理、图像生成、图像处理、令牌追踪、定价计算和工具函数六大模块，它们协同工作以提供完整的图像生成和处理解决方案。
## 架构概览
```mermaid
graph TD
A[MCP 客户端] --> B[src/index.ts]
B --> C[src/config.ts]
B --> D[src/generate.ts]
B --> E[src/process.ts]
D --> F[src/pricing.ts]
D --> G[src/tracker.ts]
D --> H[src/utils.ts]
E --> H
C --> G
G --> I[generations.jsonl]
H --> J[文件系统]
D --> K[Gemini API]
```
## 模块依赖关系
| 模块 | 职责 | 依赖模块 | 被依赖 |
|------|------|----------|--------|
| config.ts | 配置加载与验证 | - | generate.ts, process.ts |
| generate.ts | 图像生成核心逻辑 | config, pricing, tracker, utils | index.ts |
| process.ts | 本地图像处理 | utils | index.ts |
| pricing.ts | 价格计算 | - | generate.ts |
| tracker.ts | 使用量追踪 | config | generate.ts |
| utils.ts | 通用工具函数 | - | generate.ts, process.ts |
## 详细模块分析
### 1. 配置模块（config.ts）
#### 功能职责
配置模块负责集中管理所有配置参数，支持多层级配置优先级和 JSONC 格式解析。
#### 配置优先级
```mermaid
graph LR
A[环境变量] --> B[最高优先级]
C[本地配置 .gemini-image-mcp.json] --> D[中等优先级]
E[全局配置 ~/.gemini-image-mcp.json] --> F[最低优先级]
G[代码默认值] --> F
```
#### 支持的配置项
| 配置项 | 类型 | 默认值 | 说明 |
|--------|------|--------|------|
| `GEMINI_API_KEY` | string | - | Google Gemini API 密钥 |
| `MAX_REQUESTS_PER_HOUR` | number | - | 每小时最大请求数 |
| `MAX_COST_PER_HOUR` | number | - | 每小时最大成本（美元） |
| `OUTPUT_DIR` | string | ~/gemini-images | 输出目录 |
| `DEFAULT_MODEL` | string | gemini-2.5-flash-image | 默认模型 |
| `LOG_LEVEL` | string | info | 日志级别 |
| `REQUEST_TIMEOUT_MS` | number | 60000 | 请求超时（毫秒） |
#### JSONC 解析特性
- 支持字符串内嵌注释（不会破坏 URL）
- 自动移除尾部逗号
- 原型污染防护（`__proto__`, `constructor`, `prototype`）
- 未知配置键警告并丢弃
资料来源：[src/config.ts]()
### 2. 图像生成模块（generate.ts）
#### 功能职责
图像生成模块是与 Gemini API 交互的核心，负责发送请求、处理响应、管理会话和处理错误。
#### 核心参数
| 参数 | 必填 | 类型 | 说明 |
|------|------|------|------|
| prompt | 是 | string | 文本描述或编辑指令 |
| images | 否 | string[] | 输入/参考图像路径 |
| model | 否 | string | Gemini 模型 ID |
| aspectRatio | 否 | string | 宽高比 |
| resolution | 否 | string | 分辨率（1K/2K/4K） |
| sessionId | 否 | string | 多轮会话 ID |
| seed | 否 | number | 随机种子 |
| useSearchGrounding | 否 | boolean | 启用搜索 grounding |
#### 支持的模型
| 模型 | 质量 | 分辨率 | 费用 | 特点 |
|------|------|--------|------|------|
| gemini-2.5-flash-image | 快速 | 1K | ~$0.04 | 默认模型，2026年10月停用 |
| gemini-3-pro-image-preview | 最佳 | 1K/2K/4K | ~$0.15 | 最高质量，最多14张参考图 |
| gemini-3.1-flash-image-preview | 平衡 | 512/1K/2K/4K | - | 支持搜索 grounding |
#### 会话管理流程
```mermaid
sequenceDiagram
participant 客户端
participant generateImage
participant 会话管理器
participant Gemini API
客户端->>generateImage: 请求生成
alt 新会话
generateImage->>会话管理器: 创建新会话
会话管理器->>Gemini API: 首次请求
Gemini API-->>会话管理器: 返回图像 + 会话ID
会话管理器-->>generateImage: 结果 + 会话ID
else 继续会话
generateImage->>会话管理器: 获取历史
会话管理器-->>generateImage: 历史消息
generateImage->>Gemini API: 发送请求 + 历史
Gemini API-->>generateImage: 响应
end
generateImage-->>客户端: 返回结果
```
#### 关键功能
- **自动模型发现**：启动时检测可用的图像模型
- **模型验证**：每次请求验证模型可用性
- **输入图像支持**：PNG、JPEG、GIF、WebP、BMP
- **安全过滤器检测**：返回 `raiFilteredReason` 当内容被阻止
- **会话过期**：30分钟无活动自动过期
资料来源：[src/generate.ts]()
### 3. 图像处理模块（process.ts）
#### 功能职责
本地图像处理模块使用 sharp 库提供免费的图像处理功能，无需 API 调用。
#### 处理能力
| 操作 | 类型 | 说明 |
|------|------|------|
| crop | 裁剪 | 像素精确、宽高比、焦点策略 |
| resize | 缩放 | 宽、高或两者（保持宽高比） |
| removeBackground | 背景移除 | 阈值（白色背景）或色度键（绿幕） |
| trim | 修剪 | 自动移除空白/透明边框 |
| format | 格式转换 | PNG、JPEG、WebP |
| quality | 质量控制 | 1-100（JPEG/WebP） |
#### 焦点裁剪策略
| 策略 | 说明 |
|------|------|
| center | 默认，从中心裁剪 |
| attention | 移动裁剪区域到视觉焦点 |
| entropy | 移动到信息密度最高的区域 |
#### 色度键处理流程
```mermaid
graph TD
A[输入图像] --> B[HSV 颜色空间转换]
B --> C[绿色范围检测]
C --> D[Smoothstep 羽化]
D --> E[溢出色抑制]
E --> F[5次 3x3 边缘抗锯齿]
F --> G[Alpha 通道合成]
G --> H[输出透明背景图像]
```
#### 常见处理管道
```json
// 从绿幕生成透明资产
{
"imagePath": "./product-green.png",
"removeBackground": {"color": "#00FF00"},
"trim": true,
"filename": "product-transparent"
}
```
```json
// 社交卡片
{
"imagePath": "./photo.png",
"crop": {"aspectRatio": "16:9", "strategy": "attention"},
"resize": {"width": 1200}
}
```
资料来源：[src/process.ts]()
### 4. 追踪模块（tracker.ts）
#### 功能职责
追踪模块记录每次生成的详细信息，维护会话统计和生成清单。
#### 追踪数据结构
```typescript
interface GenerationRecord {
timestamp: string;
prompt: string;
model: string;
aspectRatio: string;
resolution: string;
seed?: number;
outputPath: string;
cost: number;
usage: {
promptTokens: number;
outputTokens: number;
imageTokens?: number;
thinkingTokens?: number;
};
}
```
#### 会话统计
| 统计项 | 说明 |
|--------|------|
| totalGenerations | 会话中总生成次数 |
| totalCost | 会话中总成本 |
| hourlyCount | 当前小时内的请求数 |
#### 速率限制
追踪器实时监控以下限制：
- `MAX_REQUESTS_PER_HOUR`：每小时最大请求数
- `MAX_COST_PER_HOUR`：每小时最大成本
超出限制时返回明确的错误信息和剩余配额。
资料来源：[src/tracker.ts]()
### 5. 定价模块（pricing.ts）
#### 功能职责
计算每次 API 调用的成本，提供实时成本报告。
#### 价格表
| 模型 | 输入价格 | 输出价格 |
|------|----------|----------|
| gemini-2.5-flash-image | $0.0375/1K tokens | $0.15/1K tokens |
| gemini-3-pro-image-preview | 较高 | 较高 |
| gemini-3.1-flash-image-preview | 较低 | 较低 |
#### 成本计算流程
```mermaid
graph LR
A[API 响应] --> B[提取 usage 数据]
B --> C[计算 prompt 成本]
C --> D[计算 output 成本]
D --> E[计算 image tokens 成本]
E --> F[汇总总成本]
F --> G[更新会话统计]
```
资料来源：[src/pricing.ts]()
### 6. 工具模块（utils.ts）
#### 功能职责
提供通用工具函数，支持其他核心模块的日常操作。
#### 主要工具函数
| 函数 | 功能 |
|------|------|
| resolveOutputDir | 解析并创建输出目录 |
| resolveFilename | 生成文件名，自动版本控制 |
| resolveImagePath | 解析完整图像路径 |
| readImageAsBase64 | 读取图像并转为 base64 |
| saveImage | 保存图像到磁盘 |
| createLogEntry | 创建生成日志条目 |
| extractImageFromResponse | 从 API 响应提取图像 |
#### 文件命名规则
- 用户指定名称直接使用（无扩展名，自动添加）
- 重复文件名自动添加版本后缀：`hero.png` → `hero-v2.png`
- 默认命名：`gemini-{timestamp}-{hash}.png`
#### 输出目录结构
```
OUTPUT_DIR/
├── landing-page/
│ ├── hero.png
│ └── hero-v2.png
├── social/
│ └── card-16x9.png
└── generations.jsonl
```
资料来源：[src/utils.ts]()
## 数据流图
```mermaid
graph TD
subgraph 输入层
A[用户请求] --> B[参数验证]
B --> C[配置合并]
end
subgraph 处理层
C --> D{工具类型}
D -->|generate_image| E[模型选择]
E --> F[会话管理]
F --> G[API 请求]
D -->|process_image| H[sharp 处理]
end
subgraph 输出层
G --> I[响应解析]
I --> J[图像解码]
J --> K[文件保存]
H --> K
K --> L[生成清单]
end
subgraph 追踪层
I --> M[成本计算]
M --> N[速率检查]
N --> O[会话统计]
O --> P[清单记录]
end
```
## 安全性考虑
### API 密钥保护
- 配置文件中明确警告不要提交密钥到代码库
- 环境变量优先级最高，确保密钥安全
- 启动时验证密钥有效性
### 输入验证
- Zod schema 验证所有输入参数
- 文件路径安全检查
- 原型污染防护
### 速率限制
- 可配置的请求数和成本上限
- 清晰的错误消息包含剩余配额
## 扩展指南
### 添加新模型支持
1. 在 `src/pricing.ts` 添加价格定义
2. 在 `src/generate.ts` 更新模型验证逻辑
3. 在 README 更新模型表格
### 添加新处理操作
1. 在 `src/process.ts` 添加 sharp 链式调用
2. 在 `src/index.ts` 更新 Zod schema
3. 添加相应的工具函数
### 自定义配置项
1. 在 `src/config.ts` 添加配置键
2. 实现默认值和验证逻辑
3. 在 README 文档化
## 总结
gemini-image-mcp 的核心模块设计遵循单一职责原则，通过清晰的依赖关系和标准化的接口实现灵活性和可维护性。配置模块提供统一的配置管理，生成模块处理 AI 交互，处理模块提供本地免费操作，追踪和定价模块确保透明的成本控制，工具模块则提供必要的辅助功能。
这种模块化架构使得项目易于扩展和维护，同时通过完善的错误处理和验证机制保证了生产环境的稳定性。
---
## generate_image 工具详解
### 相关页面
相关主题：[process_image 工具详解](#process-image-tool), [成本追踪与速率限制](#cost-tracking), [快速入门](#quick-start)
相关源码文件
以下源码文件用于生成本页说明：
- [src/generate.ts](https://github.com/JimothySnicket/gemini-image-mcp/blob/main/src/generate.ts)
- [src/index.ts](https://github.com/JimothySnicket/gemini-image-mcp/blob/main/src/index.ts)
- [src/config.ts](https://github.com/JimothySnicket/gemini-image-mcp/blob/main/src/config.ts)
- [package.json](https://github.com/JimothySnicket/gemini-image-mcp/blob/main/package.json)
- [README.md](https://github.com/JimothySnicket/gemini-image-mcp/blob/main/README.md)
- [server.json](https://github.com/JimothySnicket/gemini-image-mcp/blob/main/server.json)
# generate_image 工具详解
## 概述
`generate_image` 是 gemini-image-mcp MCP 服务器提供的 AI 驱动的图像生成与编辑工具，基于 Google Gemini 原生 `generateContent` API 构建。该工具支持文生图、图像编辑、多轮对话式迭代优化等功能，是从 Google 即将废弃的 Imagen API 迁移的最佳选择。
资料来源：[README.md](https://github.com/JimothySnicket/gemini-image-mcp/blob/main/README.md)
## 核心功能
### 文生图（Text-to-Image）
用户通过文本描述指定想要的图像内容，工具自动调用 Gemini 模型生成对应图像。
```json
{
"prompt": "A modern dashboard UI with dark theme and blue accent colours",
"aspectRatio": "16:9",
"resolution": "2K",
"filename": "dashboard-hero"
}
```
资料来源：[skills/image-generation/SKILL.md](https://github.com/JimothySnicket/gemini-image-mcp/blob/main/skills/image-generation/SKILL.md)
### 图像编辑（Image Editing）
支持传入参考图像，结合编辑指令对图像进行修改或重构。
```json
{
"prompt": "Change the background to a sunset over water",
"images": ["./src/assets/hero.png"],
"aspectRatio": "16:9"
}
```
资料来源：[skills/image-generation/SKILL.md](https://github.com/JimothySnicket/gemini-image-mcp/blob/main/skills/image-generation/SKILL.md)
### 多轮对话迭代
通过 `sessionId` 参数维持会话上下文，支持对图像进行多轮精细调整。每次对话都会保留对话历史，模型能够理解之前的生成结果并进行针对性修改。
```json
{
"prompt": "Make the colours warmer and add more contrast",
"sessionId": "session-1711929600000-a1b2c3"
}
```
资料来源：[skills/image-generation/SKILL.md](https://github.com/JimothySnicket/gemini-image-mcp/blob/main/skills/image-generation/SKILL.md)
## 参数详解
### 请求参数
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `prompt` | string | 是 | 文本描述或编辑指令 |
| `images` | string[] | 否 | 输入/参考图像文件路径数组 |
| `model` | string | 否 | Gemini 模型 ID |
| `aspectRatio` | string | 否 | 宽高比：`1:1`、`16:9`、`9:16`、`3:2`、`2:3`、`4:3`、`3:4`、`21:9` |
| `resolution` | string | 否 | 分辨率：`1K`、`2K`、`4K` |
| `filename` | string | 否 | 保存文件的基础名称，自动版本化 |
| `subfolder` | string | 否 | 输出目录下的子文件夹 |
| `outputDir` | string | 否 | 覆盖输出目录 |
| `sessionId` | string | 否 | 多轮会话 ID |
| `seed` | number | 否 | 整数种子，用于可复现生成 |
| `useSearchGrounding` | boolean | 否 | 启用 Google Search grounding |
资料来源：[README.md](https://github.com/JimothySnicket/gemini-image-mcp/blob/main/README.md)
### 返回结构
| 字段 | 类型 | 说明 |
|------|------|------|
| `imagePath` | string | 生成图像的保存路径 |
| `mimeType` | string | 图像 MIME 类型 |
| `model` | string | 使用的模型 |
| `tokenUsage` | object | token 使用统计 |
| `estimatedCost` | number | 预估费用（USD） |
| `session` | object | 会话统计信息 |
| `sessionId` | string | 会话 ID（用于多轮对话） |
资料来源：[src/index.ts](https://github.com/JimothySnicket/gemini-image-mcp/blob/main/src/index.ts)
## 支持的模型
| 模型 | 特点 | 分辨率 | 备注 |
|------|------|--------|------|
| `gemini-2.5-flash-image` | 快速、廉价（~$0.04/图） | 1K | 默认模型，2026年10月停用 |
| `gemini-3-pro-image-preview` | 最佳质量、文字渲染 | 1K、2K、4K | 最多14张参考图像 |
| `gemini-3.1-flash-image-preview` | 速度与质量平衡 | 512、1K、2K、4K | 支持 Google Search grounding |
资料来源：[README.md](https://github.com/JimothySnicket/gemini-image-mcp/blob/main/README.md)
## 架构设计
### 整体流程
```mermaid
graph TD
A[接收 generate_image 请求] --> B{检查 rate limit}
B -->|通过| C[加载配置]
B -->|拒绝| Z[返回限流错误]
C --> D{是否有 sessionId?}
D -->|是| E[验证 session 与模型匹配]
D -->|否| F[创建新 session]
E --> G{验证通过?}
E -->|失败| Y[返回错误]
G -->|通过| H[获取会话历史]
G -->|失败| Y
F --> H
H --> I[处理输入图像]
I --> J[调用 Gemini API]
J --> K[保存生成图像]
K --> L[更新会话历史]
L --> M[记录 generations.jsonl]
M --> N[返回结果]
```
### 模型自动发现
工具在启动时自动检测 API Key 可用的图像生成模型：
```typescript
const IMAGE_MODEL_PATTERNS = ["image", "img"];
const EXCLUDED_PREFIXES = ["imagen"];
```
资料来源：[src/generate.ts:100-104](https://github.com/JimothySnicket/gemini-image-mcp/blob/main/src/generate.ts)
### Google Search Grounding 验证
```typescript
export const GROUNDING_SUPPORTED_MODELS = ["gemini-3.1-flash-image-preview"];
export function validateGrounding(model: string, useSearchGrounding: boolean | undefined): void {
if (useSearchGrounding && !GROUNDING_SUPPORTED_MODELS.includes(model)) {
throw new Error(
`useSearchGrounding is only supported on ${GROUNDING_SUPPORTED_MODELS.join(", ")}. ` +
`You requested ${model}.`,
);
}
}
```
只有 `gemini-3.1-flash-image-preview` 模型支持 Google Search grounding 功能，其他模型使用此参数将抛出错误。
资料来源：[src/generate.ts:110-121](https://github.com/JimothySnicket/gemini-image-mcp/blob/main/src/generate.ts)
## 多轮会话管理
### 会话数据结构
```typescript
interface ConversationSession {
history: Content[];
model: string;
lastAccessed: number;
}
```
### 会话限制
| 参数 | 默认值 | 说明 |
|------|--------|------|
| `MAX_SESSION_TURNS` | 10 | 单个会话最大对话轮数 |
| `sessionTimeout` | 1800000ms (30分钟) | 会话超时时间 |
资料来源：[src/generate.ts:136-145](https://github.com/JimothySnicket/gemini-image-mcp/blob/main/src/generate.ts)
### 会话生命周期
```mermaid
graph TD
A[新请求无 sessionId] --> B[创建新会话]
A1[请求带 sessionId] --> C{会话存在?}
C -->|存在| D{超时?}
C -->|不存在| E[返回错误]
D -->|超时| E
D -->|未超时| F[更新 lastAccessed]
B --> G[生成图像]
F --> G
G --> H[追加到 history]
H --> I[返回 sessionId]
E --> J[返回错误: 会话不存在或已过期]
```
### 会话清理机制
服务器定期清理过期会话，避免内存泄漏：
```typescript
function cleanupSessions(): void {
const timeout = getSessionTimeout();
const now = Date.now();
for (const [id, session] of sessions) {
if (now - session.lastAccessed > timeout) {
sessions.delete(id);
}
}
}
```
资料来源：[src/generate.ts:153-160](https://github.com/JimothySnicket/gemini-image-mcp/blob/main/src/generate.ts)
## 图像输入处理
### 支持的格式
| 扩展名 | MIME 类型 |
|--------|-----------|
| `.png` | `image/png` |
| `.jpg` / `.jpeg` | `image/jpeg` |
| `.webp` | `image/webp` |
| `.gif` | `image/gif` |
| `.bmp` | `image/bmp` |
### 文件大小限制
最大支持 50MB 的图像文件：
```typescript
const MAX_IMAGE_SIZE = 50 * 1024 * 1024; // 50MB
```
资料来源：[src/generate.ts:129-138](https://github.com/JimothySnicket/gemini-image-mcp/blob/main/src/generate.ts)
### 错误处理
如果图像格式不支持，将抛出详细错误信息：
```typescript
throw new Error(
`Unsupported image format "${ext}" for file: ${filepath}. ` +
`Supported: ${Object.keys(MIME_TYPES).join(", ")}`,
);
```
资料来源：[src/generate.ts:122-127](https://github.com/JimothySnicket/gemini-image-mcp/blob/main/src/generate.ts)
## 成本控制
### 速率限制
可通过环境变量配置每小时请求数和费用上限：
| 环境变量 | 默认值 | 说明 |
|----------|--------|------|
| `MAX_REQUESTS_PER_HOUR` | 0 (无限制) | 每小时最大请求数 |
| `MAX_COST_PER_HOUR` | 0 (无限制) | 每小时最大费用（USD） |
资料来源：[README.md](https://github.com/JimothySnicket/gemini-image-mcp/blob/main/README.md)
### 费用报告
每次响应都包含详细费用信息：
```json
{
"tokenUsage": {
"inputTokens": 150,
"outputTokens": 200,
"totalTokens": 350
},
"estimatedCost": 0.04,
"session": {
"generationsThisSession": 5,
"totalCostThisSession": 0.20,
"generationsThisHour": 12,
"costThisHour": 0.48
}
}
```
## 配置优先级
工具支持多层配置，按优先级从高到低：
1. **请求参数** - API 调用时传入的具体参数
2. **环境变量** - `GEMINI_API_KEY` 等
3. **本地配置文件** - `./.gemini-image-mcp.json`
4. **全局配置文件** - `~/.gemini-image-mcp.json`
5. **默认值** - 代码中的默认配置
### 配置文件示例
```json
{
"defaultModel": "gemini-3.1-flash-image-preview",
"defaults": {
"generate": {
"aspectRatio": "16:9",
"resolution": "2K"
}
},
"maxRequestsPerHour": 20,
"maxCostPerHour": 5
}
```
资料来源：[README.md](https://github.com/JimothySnicket/gemini-image-mcp/blob/main/README.md)
## 输出组织
### 文件命名
- `filename` 参数用于指定基础文件名
- 自动版本化：同名文件生成时，序号递增（`hero.png` → `hero-v2.png` → `hero-v3.png`）
### 目录结构
```
outputDir/
└── subfolder/
└── filename.png
```
示例：`filename: "hero"`, `subfolder: "landing-page"` → `~/gemini-images/landing-page/hero.png`
### 生成记录
每次生成都会追加到 `generations.jsonl` 日志文件：
```jsonl
{"prompt": "...", "model": "...", "cost": 0.04, "path": "...", "timestamp": "..."}
```
## 最佳实践
### 提示词结构
建议按照以下格式构建提示词：
```
[风格] [主体] [构图] [氛围/背景]
```
示例：`"A photorealistic product shot of headphones on marble, 4K, studio lighting, centered"`
### 种子复现
使用 `seed` 参数确保相同输入产生相同输出：
```json
{
"prompt": "A blue rubber duck",
"seed": 42
}
```
### 图像编辑建议
- 使用 `sessionId` 进行迭代优化，而非将输出图像作为新输入传回
- 会话保留对话上下文，生成效果更一致
- 模型失配检测会阻止使用不同模型继续同一会话
## 技术栈
| 组件 | 版本 | 用途 |
|------|------|------|
| `@google/genai` | ^1.44.0 | Gemini API 客户端 |
| `@modelcontextprotocol/sdk` | ^1.22.0 | MCP 协议实现 |
| `zod` | ^3.24.0 | 参数验证 |
| `typescript` | ^6.0.3 | 类型安全 |
资料来源：[package.json](https://github.com/JimothySnicket/gemini-image-mcp/blob/main/package.json)
---
## process_image 工具详解
### 相关页面
相关主题：[generate_image 工具详解](#generate-image-tool), [核心模块分析](#core-modules)
相关源码文件
以下源码文件用于生成本页说明：
- [src/index.ts](https://github.com/JimothySnicket/gemini-image-mcp/blob/main/src/index.ts)
- [src/process.ts](https://github.com/JimothySnicket/gemini-image-mcp/blob/main/src/process.ts)
- [src/config.ts](https://github.com/JimothySnicket/gemini-image-mcp/blob/main/src/config.ts)
- [package.json](https://github.com/JimothySnicket/gemini-image-mcp/blob/main/package.json)
- [README.md](https://github.com/JimothySnicket/gemini-image-mcp/blob/main/README.md)
# process_image 工具详解
`process_image` 是 gemini-image-mcp 项目中的本地图像处理工具，基于 `sharp` 库实现。该工具完全免费、无需 API 调用，提供裁剪、缩放、背景移除、边框去除和格式转换等核心图像处理功能。 资料来源：[README.md]()
## 核心特性概览
| 功能 | 说明 |
|------|------|
| **Crop** | 像素精确、宽高比、焦点策略（attention/entropy）三种裁剪模式 |
| **Resize** | 支持指定宽度、高度或同时指定，保持宽高比 |
| **背景移除** | 阈值处理（白色背景）或色度键控（绿幕/任意纯色） |
| **Trim** | 自动去除白边/透明边框 |
| **格式转换** | PNG、JPEG、WebP，支持质量控制 |
资料来源：[README.md]()
## 架构设计
### 模块依赖
```mermaid
graph TD
A[process_image MCP Tool] --> B[processImage 函数]
B --> C[sharp 库]
B --> D[loadConfig 配置加载]
C --> E[裁剪模块]
C --> F[缩放模块]
C --> G[背景移除模块]
C --> H[修整模块]
C --> I[格式转换模块]
```
`process_image` 工具的核心实现位于 `src/process.ts`，通过 `src/index.ts` 中的 MCP 协议定义暴露给外部。工具内部调用 `sharp` 库进行所有图像操作，支持链式调用多个处理步骤。 资料来源：[src/index.ts:1-200](), [src/process.ts]()
### 处理流程
```mermaid
graph LR
A[输入图像] --> B[加载配置]
B --> C{参数验证}
C -->|通过| D[sharp 加载图像]
C -->|失败| E[返回错误]
D --> F[链式处理]
F --> G[裁剪?]
G -->|是| H[执行 Crop]
G -->|否| I[缩放?]
H --> I
I -->|是| J[执行 Resize]
I -->|否| K[背景移除?]
J --> K
K -->|是| L[执行 RemoveBG]
K -->|否| M[Trim?]
L --> M
M -->|是| N[执行 Trim]
M -->|否| O[格式转换?]
N --> O
O -->|是| P[执行 Format]
O -->|否| Q[保存图像]
P --> Q
Q --> R[返回结果]
```
## 参数详解
### 必选参数
| 参数 | 类型 | 说明 |
|------|------|------|
| `imagePath` | string | 输入图像的文件路径 |
资料来源：[src/index.ts]()
### 可选参数
#### 裁剪选项 (crop)
```json
// 像素精确裁剪
{"width": 500, "height": 300, "left": 100, "top": 50}
// 宽高比裁剪 (中心裁剪)
{"aspectRatio": "16:9"}
// 焦点裁剪
{"aspectRatio": "16:9", "strategy": "attention"}
{"aspectRatio": "16:9", "strategy": "entropy"}
```
| 策略 | 说明 |
|------|------|
| `center` | 默认值，从中心裁剪 |
| `attention` | 将裁剪区域移向视觉焦点区域 |
| `entropy` | 将裁剪区域移向信息熵最大的区域 |
#### 缩放选项 (resize)
```json
// 仅指定宽度
{"width": 1200}
// 仅指定高度
{"height": 800}
// 同时指定 (保持宽高比)
{"width": 1200, "height": 800}
```
#### 背景移除选项 (removeBackground)
```json
// 阈值处理 (白色背景)
{"threshold": 230}
// 色度键控 (绿幕)
{"color": "#00FF00"}
// 色度键控 (任意颜色)
{"color": "#FF0000"}
```
#### 输出选项
| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `trim` | boolean | - | 自动去除边框空白 |
| `format` | string | 原格式 | 输出格式: `png`, `jpeg`, `webp` |
| `quality` | number | 90 | JPEG/WebP 质量 (1-100) |
| `filename` | string | - | 保存文件名，自动版本号 |
| `subfolder` | string | - | 输出子文件夹 |
| `outputDir` | string | 配置值 | 输出目录 |
资料来源：[README.md](), [src/index.ts]()
## 色度键控技术
### HSV 色彩空间键控
色度键控（Chroma Key）功能采用 HSV 颜色空间进行背景识别，相比 RGB 空间具有更好的光照适应性。
```mermaid
graph TD
A[输入图像] --> B[转换到 HSV 色彩空间]
B --> C[计算色相差异]
C --> D[生成 Alpha 蒙版]
D --> E[Smoothstep 羽化]
E --> F[溢出色抑制]
F --> G[5x5 边缘抗锯齿]
G --> H[输出带透明通道图像]
```
### 处理阶段
| 阶段 | 功能 |
|------|------|
| HSV 键控 | 基于色相距离判断像素属于背景的概率 |
| Smoothstep 羽化 | 使用平滑过渡避免硬边缘 |
| 溢出色抑制 | 修正边缘处的背景色残留 |
| 边缘抗锯齿 | 5通道 3x3 卷积实现平滑边缘 |
资料来源：[README.md]()
### 使用场景
| 场景 | 推荐方案 |
|------|----------|
| 高对比度主体（红、蓝、黑在绿幕上） | 色度键控 + trim |
| 黄色主体 | 画布方法（生成到纯色背景再用 AI 处理） |
| 玻璃/反光物体 | 画布方法 |
| 白色背景 | 阈值处理 (threshold: 230) |
```json
// 高对比度主体的两步流程
// Step 1: 生成绿幕图像
{"prompt": "A product photo on a bright green background"}
// Step 2: 本地抠图
{
"imagePath": "./product-green.png",
"removeBackground": {"color": "#00FF00"},
"trim": true
}
```
资料来源：[README.md](), [skills/image-generation/SKILL.md]()
## 配置集成
### 默认配置覆盖
`process_image` 工具接受两种配置来源：
1. **全局配置**: `~/.gemini-image-mcp.json`
2. **本地配置**: `.gemini-image-mcp.json` (项目目录)
```json
{
"defaults": {
"process": {
"removeBackground": {"color": "#00FF00"},
"trim": true
}
}
}
```
配置优先级：**请求参数 > 本地配置 > 全局配置 > 默认值**
资料来源：[README.md]()
### 输出目录解析
输出目录的优先级顺序为：
```mermaid
graph TD
A[outputDir 参数] --> B{存在?}
B -->|是| C[使用参数值]
B -->|否| D[outputDir 配置?]
D -->|是| E[使用配置值]
D -->|否| F[OUTPUT_DIR 环境变量?]
F -->|是| G[使用环境变量]
F -->|否| H[~/gemini-images 默认目录]
```
## 典型使用场景
### 场景一：Favicon 生成
```json
{
"imagePath": "./logo.png",
"removeBackground": {"threshold": 230},
"trim": true,
"resize": {"width": 192, "height": 192},
"filename": "favicon-192"
}
```
### 场景二：社交媒体卡片
```json
{
"imagePath": "./photo.png",
"crop": {"aspectRatio": "16:9", "strategy": "attention"},
"resize": {"width": 1200}
}
```
### 场景三：WebP 格式转换
```json
{
"imagePath": "./banner.png",
"format": "webp",
"quality": 85
}
```
### 场景四：透明资产流水线
```mermaid
graph LR
A[generate_image
绿幕产品图] --> B[process_image
色度键控]
B --> C[process_image
trim 去白边]
C --> D[process_image
resize 调整尺寸]
D --> E[最终透明 PNG]
```
```json
// 完整流水线
[
{"prompt": "A product photo on a bright green background", "filename": "product-green"},
{"imagePath": "./product-green.png", "removeBackground": {"color": "#00FF00"}, "trim": true, "filename": "product-transparent"},
{"imagePath": "./product-transparent.png", "resize": {"width": 800, "height": 600}}
]
```
资料来源：[README.md]()
## 技术实现
### 依赖关系
| 包名 | 用途 | 版本 |
|------|------|------|
| `sharp` | 图像处理核心库 | ^0.34.5 |
| `zod` | 参数验证 | ^3.24.0 |
```json
// package.json 中的相关依赖
{
"dependencies": {
"sharp": "^0.34.5",
"zod": "^3.24.0"
}
}
```
资料来源：[package.json]()
### 错误处理
工具在以下情况会抛出错误：
| 错误场景 | 处理方式 |
|----------|----------|
| 不支持的图像格式 | 抛出 `Error` 并列出支持的格式 |
| 图像文件过大 (>50MB) | 抛出 `Error` 提示文件大小限制 |
| 处理操作失败 | 捕获异常并返回错误信息 |
## 与 generate_image 的对比
| 特性 | generate_image | process_image |
|------|----------------|---------------|
| **费用** | API 调用（~0.04美元/图） | 免费 |
| **速度** | 6-16秒 | 毫秒级 |
| **能力** | AI 智能编辑、风格迁移 | 像素级精确操作 |
| **背景移除** | 任意背景（AI驱动） | 仅纯色背景 |
| **适用场景** | 复杂编辑、创意生成 | 批量处理、格式转换 |
推荐流程：`generate_image` 生成 → `process_image` 精修
资料来源：[README.md](), [skills/image-generation/SKILL.md]()
---
## 配置指南
### 相关页面
相关主题：[核心模块分析](#core-modules), [部署与客户端集成](#deployment-guide)
相关源码文件
以下源码文件用于生成本页说明：
- [src/config.ts](https://github.com/JimothySnicket/gemini-image-mcp/blob/main/src/config.ts)
- [src/config.test.ts](https://github.com/JimothySnicket/gemini-image-mcp/blob/main/src/config.test.ts)
- [src/config.template.ts](https://github.com/JimothySnicket/gemini-image-mcp/blob/main/src/config.template.ts)
- [README.md](https://github.com/JimothySnicket/gemini-image-mcp/blob/main/README.md)
- [CHANGELOG.md](https://github.com/JimothySnicket/gemini-image-mcp/blob/main/CHANGELOG.md)
# 配置指南
## 概述
gemini-image-mcp 提供了一套集中化的配置管理系统，用于管理 MCP 服务器的各项运行时参数。该系统支持多种配置来源，包括环境变量、JSON 配置文件，并实现了明确的优先级覆盖机制。资料来源：[src/config.ts:1-50]()
配置系统的主要职责包括：
- **配置加载**：从多个来源加载配置并合并
- **JSONC 解析**：支持带注释的 JSON 配置文件
- **深度合并**：将多个配置源合并为最终配置
- **参数验证**：确保配置值的有效性和安全性
- **缓存机制**：避免重复的文件 I/O 操作
## 配置优先级
系统采用明确的优先级层次，从高到低依次为：
```
环境变量 > 本地配置 > 全局配置 > 默认值
```
资料来源：[README.md:设置](#setup)
### 优先级层次详解
| 优先级 | 配置来源 | 文件位置 |
|--------|----------|----------|
| 1 (最高) | 环境变量 | `process.env` |
| 2 | 本地配置 | `./.gemini-image-mcp.json` |
| 3 | 全局配置 | `~/.gemini-image-mcp.json` |
| 4 (最低) | 代码默认值 | `config.template.ts` |
当多个配置源包含相同键时，优先级较高的配置源将覆盖优先级较低的配置源。资料来源：[src/config.ts:100-120]()
## 配置文件
### 初始化配置文件
通过命令行可以快速生成配置文件模板：
```bash
# 创建全局配置文件
npx @jimothy-snicket/gemini-image-mcp --init
# 创建项目本地配置文件
npx @jimothy-snicket/gemini-image-mcp --init --local
```
资料来源：[README.md:#setup](#setup)
### 配置文件格式
配置文件使用 JSONC 格式（带注释的 JSON），允许在配置文件中添加内联注释：
```jsonc
{
// 默认模型设置
"defaultModel": "gemini-3.1-flash-image-preview",
// 默认值设置
"defaults": {
"generate": {
"aspectRatio": "16:9",
"resolution": "2K"
},
"process": {
"removeBackground": { "color": "#00FF00" },
"trim": true
}
}
}
```
资料来源：[src/config.template.ts:1-50]()
## 配置结构
### 完整配置对象
```typescript
interface Config {
// API 相关
apiKey?: string;
baseUrl?: string;
requestTimeoutMs?: number;
// 输出相关
outputDir?: string;
// 模型相关
defaultModel?: string;
// 日志相关
logLevel?: "debug" | "info" | "warn" | "error";
// 速率限制
maxRequestsPerHour?: number;
maxCostPerHour?: number;
// 默认值配置
defaults: {
generate: GenerateDefaults;
process: ProcessDefaults;
};
}
```
资料来源：[src/config.ts:15-35]()
### 生成工具默认值
```typescript
interface GenerateDefaults {
model?: string;
aspectRatio?: string;
resolution?: string;
useSearchGrounding?: boolean;
}
```
### 处理工具默认值
```typescript
interface ProcessDefaults {
removeBackground?: RemoveBackgroundOptions;
trim?: boolean;
format?: "png" | "jpeg" | "webp";
quality?: number;
}
```
资料来源：[src/config.ts:37-50]()
## 环境变量
### 支持的环境变量
| 变量名 | 类型 | 描述 | 默认值 |
|--------|------|------|--------|
| `GEMINI_API_KEY` | string | Google Gemini API 密钥 | - |
| `BASE_URL` | string | API 基础 URL | - |
| `OUTPUT_DIR` | string | 输出目录 | `~/gemini-images` |
| `DEFAULT_MODEL` | string | 默认模型 ID | `gemini-2.5-flash-image` |
| `LOG_LEVEL` | string | 日志级别 | `info` |
| `REQUEST_TIMEOUT_MS` | number | 请求超时(毫秒) | `60000` |
| `MAX_REQUESTS_PER_HOUR` | number | 每小时最大请求数 | - |
| `MAX_COST_PER_HOUR` | number | 每小时最大成本(USD) | - |
资料来源：[CHANGELOG.md:0.3.0 Changed](#changed) 和 [src/config.ts:50-80]()
### API 密钥配置
**重要安全提示**：API 密钥不应存储在配置文件中，因为配置文件可能被提交到代码仓库。
```bash
# 正确的做法：使用环境变量
export GEMINI_API_KEY="your-key-here"
# 配置文件中的 API 密钥会被警告并拒绝
```
资料来源：[CHANGELOG.md:Security](#security)
## 配置加载流程
```mermaid
graph TD
A[启动配置加载] --> B{检查缓存}
B -->|命中| C[返回缓存配置]
B -->|未命中| D[加载全局配置]
D --> E[加载本地配置]
E --> F[加载环境变量]
F --> G[深度合并配置]
G --> H{原型污染检查}
H -->|检测到| I[拒绝危险配置]
H -->|安全| J[验证配置值]
J --> K[缓存并返回]
```
资料来源：[src/config.ts:80-150]()
## 深度合并策略
配置系统使用深度合并算法，将多个配置源合并为单一配置对象：
```typescript
deepMerge(target: Record, source: Record): Record
```
合并规则：
- **数组覆盖**：源数组完全替换目标数组（非合并）
- **对象递归**：嵌套对象递归合并
- **原类型保留**：保持目标值的原始类型
资料来源：[src/config.test.ts:100-150]()
## 安全机制
### 原型污染防护
配置系统实现了原型污染攻击防护，检查以下危险键：
- `__proto__`
- `constructor`
- `prototype`
```typescript
// 示例：以下配置将被拒绝
{
"__proto__": { "isAdmin": true },
"constructor": { "prototype": { "malicious": true } }
}
```
资料来源：[CHANGELOG.md:Security](#security)
### API 密钥保护
配置文件中的 API 密钥会被检测并警告：
```
[安全警告] 配置文件中的 API 密钥已被拒绝。请使用环境变量 GEMINI_API_KEY
```
资料来源：[src/config.ts:150-180]()
### JSONC 注释解析安全
字符串中包含的 URL 或 JSON 片段不会被误解析为注释：
```jsonc
{
"url": "https://example.com/api?key=abc123", // 注释
"data": "{\"key\": \"value\"}" // 这是字符串，不是 JSON
}
```
资料来源：[CHANGELOG.md:Security](#security)
## 配置验证
### 模型验证
系统在启动时会验证 API 密钥并自动发现可用的图像生成模型：
```typescript
async autoDiscoverModels(): Promise
```
发现过程：
1. 调用 Gemini API 列出可用模型
2. 过滤掉 Imagen 模型（已于 2026 年 6 月废弃）
3. 返回支持图像生成的模型列表
资料来源：[CHANGELOG.md:Added](#added)
### 参数验证
使用 Zod 进行运行时参数验证：
```typescript
const generateImageSchema = z.object({
prompt: z.string(),
model: z.string().optional(),
aspectRatio: z.enum(["1:1", "16:9", ...]).optional(),
// ...
});
```
资料来源：[src/index.ts:1-100]()
## 使用示例
### 基础配置
创建 `~/.gemini-image-mcp.json`：
```json
{
"outputDir": "~/gemini-images",
"defaultModel": "gemini-3.1-flash-image-preview",
"logLevel": "info"
}
```
### 工具默认值配置
```json
{
"defaultModel": "gemini-3.1-flash-image-preview",
"defaults": {
"generate": {
"aspectRatio": "16:9",
"resolution": "2K"
},
"process": {
"removeBackground": { "color": "#00FF00" },
"trim": true
}
}
}
```
配置后，每次调用 `generate_image` 时默认使用 16:9 纵横比和 2K 分辨率。资料来源：[README.md:Per-tool defaults](#per-tool-defaults)
### 速率限制配置
```bash
# 设置每小时最多 20 次请求
export MAX_REQUESTS_PER_HOUR=20
# 设置每小时最大成本 5 美元
export MAX_COST_PER_HOUR=5
```
```json
{
"maxRequestsPerHour": 20,
"maxCostPerHour": 5
}
```
资料来源：[README.md:Rate limiting](#rate-limiting)
## 调试配置
### 日志级别
| 级别 | 用途 |
|------|------|
| `debug` | 详细调试信息，包括 API 响应结构 |
| `info` | 一般信息性消息 |
| `warn` | 警告信息 |
| `error` | 错误消息 |
```bash
export LOG_LEVEL=debug
```
### 请求超时
```bash
# 设置 120 秒超时
export REQUEST_TIMEOUT_MS=120000
```
```json
{
"requestTimeoutMs": 120000
}
```
## 常见问题
### Q: 配置文件修改后需要重启吗？
是的。配置在服务器启动时加载，修改配置文件后需要重启 MCP 服务器。
### Q: 如何查看当前生效的配置？
目前没有命令直接查看合并后的配置。可通过检查各配置源文件来确认配置状态。
### Q: 为什么不支持从配置文件读取 API 密钥？
出于安全考虑。配置文件可能被提交到版本控制系统（如 Git），导致密钥泄露。
### Q: 如何重置为默认配置？
删除配置文件并重新初始化：
```bash
rm ~/.gemini-image-mcp.json
npx @jimothy-snicket/gemini-image-mcp --init
```
## 变更历史
| 版本 | 日期 | 变更内容 |
|------|------|----------|
| 0.4.0 | 2026-05 | 新增配置模块，支持 JSONC 解析和深度合并 |
| 0.3.0 | 2026-04 | 新增 `process_image` 工具和会话跟踪 |
| 0.2.0 | 2026-04 | 初始发布 |
资料来源：[CHANGELOG.md](#changelog)
---
## 部署与客户端集成
### 相关页面
相关主题：[快速入门](#quick-start), [配置指南](#configuration-guide)
相关源码文件
以下源码文件用于生成本页说明：
- [README.md](https://github.com/JimothySnicket/gemini-image-mcp/blob/main/README.md)
- [server.json](https://github.com/JimothySnicket/gemini-image-mcp/blob/main/server.json)
- [package.json](https://github.com/JimothySnicket/gemini-image-mcp/blob/main/package.json)
- [CONTRIBUTING.md](https://github.com/JimothySnicket/gemini-image-mcp/blob/main/CONTRIBUTING.md)
- [src/index.ts](https://github.com/JimothySnicket/gemini-image-mcp/blob/main/src/index.ts)
# 部署与客户端集成
## 概述
`gemini-image-mcp` 是一个基于 Model Context Protocol (MCP) 的服务器，为 AI 图像生成和处理提供标准化的工具接口。该项目通过 MCP 协议与各种 AI 客户端集成，支持文本到图像生成、图像编辑、本地图像处理等功能。
核心能力包括：
- **generate_image** — 调用 Google Gemini API 生成或编辑图像
- **process_image** — 本地图像处理（裁剪、缩放、背景移除等），无需 API 调用
资料来源：[README.md:1-15]()
## 部署架构
### 系统组件
```mermaid
graph TD
subgraph 客户端层
A[Claude Code]
B[Claude Desktop]
C[通用 MCP 客户端]
end
subgraph MCP 协议层
D[MCP SDK]
E[STDIO 传输]
end
subgraph 服务层
F[gemini-image-mcp Server]
G[generate_image 工具]
H[process_image 工具]
end
subgraph 外部服务
I[Google Gemini API]
end
A --> D
B --> D
C --> D
D --> E
E --> F
F --> G
F --> H
G --> I
H --> I
style G fill:#90EE90
style H fill:#90EE90
```
### 服务入口点
服务器通过 STDIO 传输与 MCP 客户端通信，支持两种启动方式：
| 方式 | 命令 | 用途 |
|------|------|------|
| 全局安装 | `npx @jimothy-snicket/gemini-image-mcp` | 临时运行 |
| 本地开发 | `bun run dev` | 源码调试 |
| 构建后运行 | `bun run build && bun dist/index.js` | 生产部署 |
资料来源：[package.json:1-20]()
资料来源：[CONTRIBUTING.md:1-15]()
## 环境配置
### API 密钥设置
服务器需要 `GEMINI_API_KEY` 环境变量才能正常启动。密钥必须从 Google AI Studio 获取。
**Windows (PowerShell):**
```powershell
[System.Environment]::SetEnvironmentVariable('GEMINI_API_KEY', 'your-key-here', 'User')
```
**macOS / Linux:**
```bash
echo 'export GEMINI_API_KEY="your-key-here"' >> ~/.bashrc
source ~/.bashrc
```
验证配置：
```bash
echo $GEMINI_API_KEY
```
资料来源：[README.md:30-50]()
### 配置文件
除了环境变量，还支持 JSON 配置文件方式。初始化配置文件：
```bash
npx @jimothy-snicket/gemini-image-mcp --init
```
此命令在用户主目录创建 `~/.gemini-image-mcp.json`，包含所有可配置项及说明文档。
**配置优先级：**
```
环境变量 > 本地配置 (.gemini-image-mcp.json) > 全局配置 (~/.gemini-image-mcp.json) > 默认值
```
**配置文件结构：**
| 字段 | 类型 | 说明 |
|------|------|------|
| `defaultModel` | string | 默认使用的 Gemini 模型 |
| `defaults.generate` | object | generate_image 默认参数 |
| `defaults.process` | object | process_image 默认参数 |
| `outputDir` | string | 图像输出目录 |
| `maxRequestsPerHour` | number | 每小时最大请求数 |
| `maxCostPerHour` | number | 每小时最大成本（美元） |
资料来源：[README.md:80-115]()
## MCP 服务器配置
### server.json 清单
每个 MCP 服务器需要通过 `server.json` 声明其元数据。`gemini-image-mcp` 的配置如下：
```json
{
"name": "io.github.JimothySnicket/gemini-image",
"description": "Google Gemini image generation, editing, and local processing via MCP",
"version": "0.4.0",
"packages": [{
"identifier": "@jimothy-snicket/gemini-image-mcp",
"version": "0.4.0",
"transport": { "type": "stdio" },
"environmentVariables": [{
"name": "GEMINI_API_KEY",
"description": "Google Gemini API key",
"isRequired": true,
"isSecret": true
}]
}]
}
```
关键配置说明：
| 字段 | 值 | 说明 |
|------|-----|------|
| `transport.type` | stdio | 使用标准输入/输出通信 |
| `isSecret` | true | 敏感变量，客户端应安全处理 |
| `isRequired` | true | 必需的环境变量 |
资料来源：[server.json:1-30]()
## 客户端集成指南
### Claude Code 集成
Claude Code 通过插件层集成 MCP 工具。项目包含：
- `plugin.json` — 插件清单
- `skills/image-generation/SKILL.md` — 技能说明
集成步骤：
1. 确保 `gemini-image-mcp` 全局安装并配置好 API 密钥
2. Claude Code 自动发现可用工具
3. 使用 `generate_image` 和 `process_image` 工具
**技能使用示例：**
```json
{
"prompt": "A modern dashboard UI with dark theme and blue accent colours",
"aspectRatio": "16:9",
"resolution": "2K",
"filename": "dashboard-hero"
}
```
Claude Code 可直接调用工具，工具响应包含 token 使用量、预估成本和会话统计。
资料来源：[skills/image-generation/SKILL.md:1-60]()
### Claude Desktop 集成
在 Claude Desktop 的 MCP 配置中添加服务器：
```json
{
"mcpServers": {
"gemini-image": {
"command": "npx",
"args": ["@jimothy-snicket/gemini-image-mcp"],
"env": {
"GEMINI_API_KEY": "your-api-key"
}
}
}
}
```
配置文件位置：
- **macOS/Linux:** `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
资料来源：[README.md:55-75]()
### 通用 MCP 客户端
对于其他 MCP 兼容客户端，配置格式类似：
```json
{
"mcpServers": {
"gemini-image-mcp": {
"command": "bun",
"args": ["path/to/dist/index.js"],
"env": {
"GEMINI_API_KEY": "your-api-key"
}
}
}
}
```
构建用于生产部署：
```bash
bun install
bun run build
```
资料来源：[CONTRIBUTING.md:8-12]()
## 工具接口
### generate_image
通过 Gemini API 生成或编辑图像。
| 参数 | 必填 | 说明 |
|------|------|------|
| `prompt` | 是 | 图像描述或编辑指令 |
| `images` | 否 | 参考图像文件路径数组 |
| `model` | 否 | Gemini 模型 ID |
| `aspectRatio` | 否 | 宽高比（1:1, 16:9, 9:16 等） |
| `resolution` | 否 | 分辨率（1K, 2K, 4K） |
| `sessionId` | 否 | 多轮编辑会话 ID |
| `seed` | 否 | 整数种子，用于可复现生成 |
资料来源：[src/index.ts:40-100]()
### process_image
本地图像处理，无需 API 调用。
| 参数 | 必填 | 说明 |
|------|------|------|
| `imagePath` | 是 | 源图像文件路径 |
| `crop` | 否 | 裁剪参数 |
| `resize` | 否 | 缩放参数 |
| `removeBackground` | 否 | 背景移除参数 |
| `trim` | 否 | 去除空白边框 |
| `format` | 否 | 输出格式（png/jpeg/webp） |
| `quality` | 否 | JPEG/WebP 质量（1-100） |
资料来源：[README.md:95-120]()
## 可用模型
| 模型 | 特点 | 分辨率 | 备注 |
|------|------|--------|------|
| `gemini-2.5-flash-image` | 快速、低成本 | 1K | 默认模型，2026年10月停用 |
| `gemini-3-pro-image-preview` | 最佳质量，支持文本渲染 | 1K, 2K, 4K | 最多14张参考图像 |
| `gemini-3.1-flash-image-preview` | 速度与质量平衡 | 512, 1K, 2K, 4K | 支持 Google Search grounding |
服务器启动时自动发现可用的图像模型，验证 API 密钥有效性。
资料来源：[README.md:130-140]()
## 速率限制
生产环境中使用速率限制防止成本失控：
| 环境变量 | 默认值 | 说明 |
|----------|--------|------|
| `MAX_REQUESTS_PER_HOUR` | 未设置 | 每小时最大请求数 |
| `MAX_COST_PER_HOUR` | 未设置 | 每小时最大成本（美元） |
**推荐配置：**
```bash
MAX_REQUESTS_PER_HOUR=20
MAX_COST_PER_HOUR=5
```
速率超限返回明确错误，包含剩余预算信息。Agent 循环使用时应配置这些限制。
资料来源：[README.md:75-80]()
## 开发与调试
### 本地开发环境
```bash
bun install # 安装依赖
bun run build # TypeScript 编译到 dist/
bun run dev # 直接运行源码（热重载）
```
需要设置 `GEMINI_API_KEY` 环境变量用于测试图像生成。
### 日志级别
通过 `LOG_LEVEL` 环境变量控制日志详细程度：
```bash
LOG_LEVEL=debug bun run dev
```
### 请求超时
默认请求超时 60 秒，可通过 `REQUEST_TIMEOUT_MS` 调整。
资料来源：[CONTRIBUTING.md:5-15]()
## 常见部署场景
### 场景一：独立工具服务器
```
┌─────────────┐ STDIO ┌─────────────────┐
│ Claude │ ────────────► │ gemini-image │
│ Desktop │ │ -mcp server │
└─────────────┘ └─────────────────┘
│
▼
┌─────────────────┐
│ Gemini API │
└─────────────────┘
```
适用于单用户桌面环境。
### 场景二：团队共享部署
团队成员各自配置 `~/.gemini-image-mcp.json`，使用相同的 `GEMINI_API_KEY` 或各自密钥。
```json
{
"defaultModel": "gemini-3.1-flash-image-preview",
"maxCostPerHour": 10,
"outputDir": "~/team-gemini-images"
}
```
### 场景三：CI/CD 集成
在自动化流程中使用时，确保：
1. 环境变量正确注入
2. 速率限制已配置
3. 输出目录已创建
4. 网络可访问 Gemini API
```yaml
# CI 配置示例
env:
GEMINI_API_KEY: ${{ secrets.GEMINI_API_KEY }}
MAX_COST_PER_HOUR: 2
LOG_LEVEL: info
---
## 成本追踪与速率限制
### 相关页面
相关主题：[generate_image 工具详解](#generate-image-tool), [配置指南](#configuration-guide)
相关源码文件
以下源码文件用于生成本页说明：
- [src/pricing.ts](https://github.com/JimothySnicket/gemini-image-mcp/blob/main/src/pricing.ts)
- [src/pricing.test.ts](https://github.com/JimothySnicket/gemini-image-mcp/blob/main/src/pricing.test.ts)
- [src/tracker.ts](https://github.com/JimothySnicket/gemini-image-mcp/blob/main/src/tracker.ts)
- [src/tracker.test.ts](https://github.com/JimothySnicket/gemini-image-mcp/blob/main/src/tracker.test.ts)
- [src/config.ts](https://github.com/JimothySnicket/gemini-image-mcp/blob/main/src/config.ts)
- [src/generate.ts](https://github.com/JimothySnicket/gemini-image-mcp/blob/main/src/generate.ts)
# 成本追踪与速率限制
## 概述
gemini-image-mcp 提供了完整的成本追踪和速率限制机制，用于监控 API 使用情况并防止意外超支。这两个功能相互配合，确保用户在调用 Gemini 图像生成 API 时能够清晰了解费用并控制支出。
### 核心功能
| 功能 | 描述 |
|------|------|
| 成本追踪 | 记录每次 API 调用的 token 消耗并计算 USD 成本 |
| 速率限制 | 按小时限制请求次数和总成本，防止代理意外超支 |
| 会话统计 | 跟踪会话级别的累计使用量和费用 |
| 生成日志 | 将每次生成记录写入 `generations.jsonl` 清单文件 |
资料来源：[README.md](README.md)
---
## 架构设计
### 组件关系
```mermaid
graph TD
A[用户请求] --> B[generate_image 工具]
B --> C[成本计算模块
pricing.ts]
C --> D[用量追踪模块
tracker.ts]
D --> E[速率限制检查]
E --> F{是否超限?}
F -->|否| G[调用 Gemini API]
G --> H[记录到 generations.jsonl]
H --> I[返回结果含成本信息]
F -->|是| J[返回速率限制错误]
K[配置加载
config.ts] --> C
K --> E
```
### 模块职责
| 模块 | 文件 | 职责 |
|------|------|------|
| 定价模块 | `src/pricing.ts` | 根据模型和 token 数量计算 USD 成本 |
| 追踪模块 | `src/tracker.ts` | 管理请求计数、成本累计和速率限制检查 |
| 配置模块 | `src/config.ts` | 加载和管理速率限制相关配置 |
资料来源：[src/config.ts](src/config.ts)
---
## 成本追踪系统
### 成本计算逻辑
系统根据 Gemini API 返回的用量信息计算每次调用的成本：
```typescript
// 伪代码示例
const cost = calculateCost(model, usage)
```
### Token 用量报告
每次图像生成响应都包含详细的用量统计：
```json
{
"usage": {
"promptTokens": 5,
"outputTokens": 1295,
"imageTokens": 1290,
"thinkingTokens": 412,
"totalTokens": 3002
},
"estimatedCost": 0.04,
"session": {
"generations": 1,
"totalCost": 0.04,
"totalTokens": 3002
}
}
```
| 字段 | 描述 |
|------|------|
| `promptTokens` | 输入提示的 token 数量 |
| `outputTokens` | 输出文本的 token 数量 |
| `imageTokens` | 输入图像消耗的 token 数量 |
| `thinkingTokens` | 模型思考过程的 token 数量 |
| `totalTokens` | 总 token 数量 |
| `estimatedCost` | 本次调用的 USD 估算成本 |
资料来源：[README.md:features](README.md) 资料来源：[CHANGELOG.md:0.3.0](CHANGELOG.md)
### 会话级别统计
系统通过 `sessionId` 维护会话状态，累积计算会话内的总成本：
```json
{
"session": {
"generations": 3,
"totalCost": 0.12,
"totalTokens": 9006,
"hourlyCount": 3,
"hourlyCost": 0.12
}
}
```
资料来源：[CHANGELOG.md:0.3.0](CHANGELOG.md)
---
## 速率限制机制
### 配置方式
速率限制通过环境变量或配置文件设置：
| 环境变量 | 配置文件键 | 描述 | 默认值 |
|----------|------------|------|--------|
| `MAX_REQUESTS_PER_HOUR` | `maxRequestsPerHour` | 每小时最大请求数 | 0 (无限制) |
| `MAX_COST_PER_HOUR` | `maxCostPerHour` | 每小时最大 USD 成本 | 0 (无限制) |
配置优先级：**环境变量 > 本地配置 > 全局配置 > 默认值**
资料来源：[README.md:rate-limiting](README.md)
### 配置文件示例
```json
{
"maxRequestsPerHour": 20,
"maxCostPerHour": 5,
"defaultModel": "gemini-3.1-flash-image-preview"
}
```
可通过以下命令生成配置模板：
```bash
npx @jimothy-snicket/gemini-image-mcp --init
```
资料来源：[README.md:Config File](README.md)
### 速率限制检查流程
```mermaid
graph TD
A[接收请求] --> B[检查 MAX_REQUESTS_PER_HOUR]
B --> C{当前小时请求数
>= 限制?}
C -->|是| D[拒绝请求
返回速率限制错误]
C -->|否| E[检查 MAX_COST_PER_HOUR]
E --> F{当前小时成本
>= 限制?}
F -->|是| D
F -->|否| G[执行 API 调用]
D --> H[响应包含剩余配额信息]
```
### 超限响应
当请求被速率限制拦截时，返回清晰的错误信息：
```json
{
"error": "Rate limit exceeded",
"limit": {
"type": "requests_per_hour",
"limit": 20,
"remaining": 0,
"resetAt": "2026-01-15T14:00:00Z"
}
}
```
资料来源：[README.md:rate-limiting](README.md)
---
## 生成清单
### generations.jsonl 格式
每次图像生成都会追加记录到 `generations.jsonl` 文件：
```jsonl
{"timestamp":"2026-01-15T13:45:00.000Z","prompt":"A modern dashboard UI","model":"gemini-3.1-flash-image-preview","aspectRatio":"16:9","resolution":"2K","outputPath":"/home/user/gemini-images/dashboard-hero.png","usage":{"promptTokens":5,"outputTokens":1295,"imageTokens":1290,"thinkingTokens":412,"totalTokens":3002},"estimatedCost":0.04}
{"timestamp":"2026-01-15T13:50:00.000Z","prompt":"Make the colors warmer","model":"gemini-3.1-flash-image-preview","sessionId":"session-1705329900000-a1b2c3","outputPath":"/home/user/gemini-images/dashboard-hero-v2.png","usage":{...},"estimatedCost":0.03}
```
| 字段 | 描述 |
|------|------|
| `timestamp` | ISO 8601 格式的时间戳 |
| `prompt` | 使用的提示词 |
| `model` | 调用的模型 ID |
| `sessionId` | 会话标识符（如果有） |
| `outputPath` | 生成的图像文件路径 |
| `usage` | Token 用量详情 |
| `estimatedCost` | USD 估算成本 |
资料来源：[README.md:generations.jsonl](README.md) 资料来源：[CHANGELOG.md:0.3.0](CHANGELOG.md)
---
## 模型定价参考
| 模型 | 分辨率 | 估算成本 | 备注 |
|------|--------|----------|------|
| `gemini-2.5-flash-image` | 1K | ~$0.04/图像 | 快速廉价，2026年10月停用 |
| `gemini-3-pro-image-preview` | 1K, 2K, 4K | ~$0.15/图像 | 最佳质量，支持14个参考图像 |
| `gemini-3.1-flash-image-preview` | 512, 1K, 2K, 4K | 中等 | 速度与质量平衡，支持搜索增强 |
资料来源：[README.md:Models](README.md)
---
## 安全特性
### 配置安全
系统实现了多层安全防护：
| 安全措施 | 描述 |
|----------|------|
| API 密钥验证 | 配置文件中拒绝包含 API 密钥的配置项 |
| 原型污染防护 | 深度合并时排除 `__proto__`、`constructor`、`prototype` |
| 未知配置警告 | 丢弃未知配置键，防止意外数据注入 |
资料来源：[CHANGELOG.md:0.4.0:Security](CHANGELOG.md)
### 速率限制建议
对于在循环中运行的代理程序，建议设置合理的速率限制：
```bash
MAX_REQUESTS_PER_HOUR=20
MAX_COST_PER_HOUR=5
```
资料来源：[README.md:rate-limiting](README.md)
---
## 最佳实践
1. **启用速率限制** - 生产环境中务必设置 `MAX_REQUESTS_PER_HOUR` 和 `MAX_COST_PER_HOUR`
2. **监控生成清单** - 定期检查 `generations.jsonl` 分析使用模式
3. **使用会话追踪** - 通过 `sessionId` 保持上下文并获得准确的会话统计
4. **选择合适的模型** - 快速迭代使用 `gemini-2.5-flash-image`，最终输出使用 `gemini-3-pro-image-preview`
5. **查看响应成本** - 每次响应都包含成本信息，应向用户说明费用情况
资料来源：[README.md:Important](README.md) 资料来源：[skills/image-generation/SKILL.md](skills/image-generation/SKILL.md)
---
## Gemini 模型对比
### 相关页面
相关主题：[generate_image 工具详解](#generate-image-tool), [配置指南](#configuration-guide)
相关源码文件
以下源码文件用于生成本页说明：
- [README.md](https://github.com/JimothySnicket/gemini-image-mcp/blob/main/README.md)
- [package.json](https://github.com/JimothySnicket/gemini-image-mcp/blob/main/package.json)
- [CHANGELOG.md](https://github.com/JimothySnicket/gemini-image-mcp/blob/main/CHANGELOG.md)
- [src/pricing.test.ts](https://github.com/JimothySnicket/gemini-image-mcp/blob/main/src/pricing.test.ts)
- [src/config.ts](https://github.com/JimothySnicket/gemini-image-mcp/blob/main/src/config.ts)
- [server.json](https://github.com/JimothySnicket/gemini-image-mcp/blob/main/server.json)
# Gemini 模型对比
## 概述
gemini-image-mcp 项目支持多个 Google Gemini 图像生成模型，每个模型在速度、成本、质量和功能方面各有侧重。开发者需要根据具体使用场景选择合适的模型，以达到最佳效果与成本平衡。
项目使用 `@google/genai` 库（版本 ^1.44.0）与 Gemini API 进行交互，通过 MCP（Model Context Protocol）协议提供服务。资料来源：[package.json:1-25]()
## 支持的模型列表
### 模型对比总览
| 模型名称 | 主要优势 | 支持分辨率 | 单张估算成本 | 特殊功能 | 弃用时间 |
|---------|---------|-----------|-------------|---------|---------|
| `gemini-2.5-flash-image` | 快速、便宜 | 仅 1K | ~$0.04/image | 默认模型 | 2026年10月 |
| `gemini-3-pro-image-preview` | 最佳质量、文字渲染 | 1K、2K、4K | 较高 | 最多14张参考图 | 当前预览版 |
| `gemini-3.1-flash-image-preview` | 速度与质量平衡 | 512、1K、2K、4K | 中等 | Google Search grounding | 当前预览版 |
资料来源：[README.md:1-45]()
### 模型选择流程
```mermaid
graph TD
A[开始选择模型] --> B{优先级是什么?}
B -->|速度| C[gemini-2.5-flash-image]
B -->|质量| D{genini-3-pro-image-preview}
B -->|准确度| E[gemini-3.1-flash-image-preview]
B -->|参考图数量| F{需要超过14张?}
F -->|是| E
F -->|否| D
C --> G[设置 model 参数]
D --> G
E --> G
```
## 各模型详细说明
### gemini-2.5-flash-image
**定位**：默认模型，适用于快速原型开发和低成本批量生成
**技术规格**：
- **分辨率**：仅支持 1K（1024×1024）
- **定价层级**：入门级价格，约 $0.04/张
- **适用场景**：MVP开发、快速预览、预算敏感型项目
**局限性**：
- 仅支持 1K 分辨率，无法输出更高清的图像
- 已规划在 2026年10月 弃用，建议迁移到新模型
资料来源：[README.md:40-45]()
### gemini-3-pro-image-preview
**定位**：最高质量输出，专业级图像生成
**技术规格**：
- **分辨率**：1K、2K、4K 可选
- **定价层级**：高端定价
- **参考图像**：最多支持 14 张参考图像输入
- **文字渲染**：业界领先的文字嵌入图像能力
**适用场景**：
- 产品摄影、商业海报
- 需要精确文字的营销素材
- 多参考图像的复杂编辑任务
- 需要 4K 超高清输出的项目
```mermaid
graph LR
A[14张参考图] --> B[gemini-3-pro-image-preview]
B --> C[高质量输出]
C --> D[1K/2K/4K 分辨率]
```
资料来源：[README.md:35-40]()
### gemini-3.1-flash-image-preview
**定位**：速度与质量的最佳平衡点
**技术规格**：
- **分辨率**：512、1K、2K、4K 全覆盖
- **定价层级**：中等价格
- **特色功能**：Google Search grounding（搜索 grounding）
**Google Search Grounding 优势**：
Search grounding 功能使模型能够基于 Google 搜索结果进行事实核查和内容增强，适用于：
- 需要真实世界准确性的场景
- 产品信息图（基于真实产品数据）
- 新闻配图（基于最新资讯）
- 任何需要"所见即所得"准确度的场景
资料来源：[README.md:41-45]()
## 模型选择指南
### 按使用场景选择
```mermaid
graph TD
A[选择场景] --> B{你的首要需求?}
B -->|成本最低| C[gemini-2.5-flash-image]
B -->|图像质量| D{需要4K输出?}
B -->|准确度| E[gemini-3.1-flash-image-preview]
B -->|文字渲染| F[gemini-3-pro-image-preview]
D -->|是| G[gemini-3-pro-image-preview]
D -->|否| H{需要快速迭代?}
H -->|是| I[gemini-2.5-flash-image]
H -->|否| J[gemini-3.1-flash-image-preview]
C --> K[完成选择]
G --> K
E --> K
F --> K
I --> K
J --> K
```
### 价格与质量矩阵
| 质量等级 | 模型 | 成本效率 | 推荐指数 |
|---------|------|---------|---------|
| 基础 | gemini-2.5-flash-image | ★★★★★ | MVP/原型 |
| 平衡 | gemini-3.1-flash-image-preview | ★★★★☆ | 日常生产 |
| 旗舰 | gemini-3-pro-image-preview | ★★★☆☆ | 专业输出 |
## 配置与使用
### 默认模型设置
在配置文件 `~/.gemini-image-mcp.json` 中可以设置默认模型：
```json
{
"defaultModel": "gemini-3.1-flash-image-preview",
"defaults": {
"generate": {
"aspectRatio": "16:9",
"resolution": "2K"
}
}
}
```
资料来源：[README.md:80-95]()
### 参数优先级
```
命令行参数 > 环境变量 > 本地配置 > 全局配置 > 默认值
```
项目实现了配置优先级机制，参数加载顺序为：
1. 环境变量（直接设置）
2. 本地配置文件（`.gemini-image-mcp.json`）
3. 全局配置文件（`~/.gemini-image-mcp.json`）
4. 系统默认值
资料来源：[src/config.ts:1-50]()
### API 调用示例
**指定模型生成图像**：
```json
{
"prompt": "A photorealistic product shot of headphones on marble, 4K",
"model": "gemini-3-pro-image-preview",
"aspectRatio": "16:9",
"resolution": "4K"
}
```
**使用 Search Grounding**：
```json
{
"prompt": "Generate an infographic about the latest iPhone model",
"model": "gemini-3.1-flash-image-preview",
"useSearchGrounding": true
}
```
## 成本管理
### 速率限制配置
项目支持按小时设置请求和成本上限，防止意外超支：
| 环境变量 | 默认值 | 说明 |
|---------|-------|------|
| `MAX_REQUESTS_PER_HOUR` | 20 | 每小时最大请求数 |
| `MAX_COST_PER_HOUR` | 5 | 每小时最大成本（美元） |
建议在自动化代理场景中设置这些限制：
```bash
export MAX_REQUESTS_PER_HOUR=20
export MAX_COST_PER_HOUR=5
```
资料来源：[README.md:60-75]()
### 成本计算
每次生成图像后，API 响应中包含详细的用量信息：
```json
{
"usage": {
"promptTokens": 5,
"outputTokens": 1295,
"imageTokens": 1290,
"thinkingTokens": 412,
"totalTokens": 1712,
"estimatedCost": "$0.0390"
},
"session": {
"totalCostThisSession": "$0.1161",
"remainingThisHour": 15
}
}
```
资料来源：[README.md:50-65]()
## 模型演进与迁移
### 版本时间线
```mermaid
gantt
title Gemini 模型支持时间线
dateFormat YYYY-MM
section 当前
gemini-2.5-flash-image :active, 2025-01, 2026-10
gemini-3-pro-image-preview :active, 2025-04, 2026-12
gemini-3.1-flash-image-preview :active, 2025-06, 2026-12
section 规划弃用
gemini-2.5-flash-image 弃用 :2026-10, 2026-10
```
### 从 gemini-2.5-flash-image 迁移
由于 `gemini-2.5-flash-image` 将在 2026年10月 弃用，建议：
1. **日常快速任务**：迁移至 `gemini-3.1-flash-image-preview`
2. **高质量任务**：迁移至 `gemini-3-pro-image-preview`
3. **批量自动化**：同时调整 `MAX_COST_PER_HOUR` 以适应新模型的定价
资料来源：[CHANGELOG.md:1-30]()
## 总结与建议
### 快速参考表
| 需求 | 推荐模型 | 原因 |
|-----|---------|------|
| 快速原型 | gemini-2.5-flash-image | 成本最低、速度快 |
| 生产环境平衡 | gemini-3.1-flash-image-preview | 分辨率全、价格适中 |
| 最高质量 | gemini-3-pro-image-preview | 4K支持、文字渲染强 |
| 事实准确性 | gemini-3.1-flash-image-preview | Search grounding |
| 多参考图 | gemini-3-pro-image-preview | 最多14张参考图 |
### 最佳实践
1. **开发阶段**：使用 `gemini-2.5-flash-image` 快速迭代
2. **预生产**：切换到 `gemini-3.1-flash-image-preview` 验证质量
3. **正式发布**：使用 `gemini-3-pro-image-preview` 确保最佳效果
4. **成本监控**：始终关注 `remainingThisHour` 和 `estimatedCost` 字段
通过合理选择模型，开发者可以在项目不同阶段实现成本与质量的最优平衡。
---
---
## Doramagic 踩坑日志
项目：jimothysnicket/gemini-image-mcp
摘要：发现 6 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：能力坑 - 能力判断依赖假设。
## 1. 能力坑 · 能力判断依赖假设
- 严重度：medium
- 证据强度：source_linked
- 发现：README/documentation is current enough for a first validation pass.
- 对用户的影响：假设不成立时，用户拿不到承诺的能力。
- 建议检查：将假设转成下游验证清单。
- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。
- 证据：capability.assumptions | mcp_registry:io.github.JimothySnicket/gemini-image:0.2.2 | https://registry.modelcontextprotocol.io/v0.1/servers/io.github.JimothySnicket%2Fgemini-image/versions/0.2.2 | README/documentation is current enough for a first validation pass.
## 2. 维护坑 · 维护活跃度未知
- 严重度：medium
- 证据强度：source_linked
- 发现：未记录 last_activity_observed。
- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。
- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。
- 证据：evidence.maintainer_signals | mcp_registry:io.github.JimothySnicket/gemini-image:0.2.2 | https://registry.modelcontextprotocol.io/v0.1/servers/io.github.JimothySnicket%2Fgemini-image/versions/0.2.2 | last_activity_observed missing
## 3. 安全/权限坑 · 下游验证发现风险项
- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 对用户的影响：下游已经要求复核，不能在页面中弱化。
- 建议检查：进入安全/权限治理复核队列。
- 防护动作：下游风险存在时必须保持 review/recommendation 降级。
- 证据：downstream_validation.risk_items | mcp_registry:io.github.JimothySnicket/gemini-image:0.2.2 | https://registry.modelcontextprotocol.io/v0.1/servers/io.github.JimothySnicket%2Fgemini-image/versions/0.2.2 | no_demo; severity=medium
## 4. 安全/权限坑 · 存在评分风险
- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 对用户的影响：风险会影响是否适合普通用户安装。
- 建议检查：把风险写入边界卡，并确认是否需要人工复核。
- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。
- 证据：risks.scoring_risks | mcp_registry:io.github.JimothySnicket/gemini-image:0.2.2 | https://registry.modelcontextprotocol.io/v0.1/servers/io.github.JimothySnicket%2Fgemini-image/versions/0.2.2 | no_demo; severity=medium
## 5. 维护坑 · issue/PR 响应质量未知
- 严重度：low
- 证据强度：source_linked
- 发现：issue_or_pr_quality=unknown。
- 对用户的影响：用户无法判断遇到问题后是否有人维护。
- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。
- 防护动作：issue/PR 响应未知时，必须提示维护风险。
- 证据：evidence.maintainer_signals | mcp_registry:io.github.JimothySnicket/gemini-image:0.2.2 | https://registry.modelcontextprotocol.io/v0.1/servers/io.github.JimothySnicket%2Fgemini-image/versions/0.2.2 | issue_or_pr_quality=unknown
## 6. 维护坑 · 发布节奏不明确
- 严重度：low
- 证据强度：source_linked
- 发现：release_recency=unknown。
- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。
- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。
- 证据：evidence.maintainer_signals | mcp_registry:io.github.JimothySnicket/gemini-image:0.2.2 | https://registry.modelcontextprotocol.io/v0.1/servers/io.github.JimothySnicket%2Fgemini-image/versions/0.2.2 | release_recency=unknown