项目概述

gemini-image-mcp 是一个基于 Google Gemini API 的模型上下文协议（Model Context Protocol，MCP）服务器，专门用于图像生成、编辑和本地图像处理。 资料来源：README.md

该项目由 Jamie Donaldson 开发，采用 MIT 开源许可证发布。通过 MCP 协议，该工具可以与 Claude Code、Claude Desktop 等多种 AI 助手无缝集成，为用户提供强大的 AI 图像处理能力。 资料来源：package.json

核心特性

技术架构

技术栈

项目采用现代 TypeScript 技术栈构建，主要依赖包括：

资料来源：package.json

模块组成

项目源代码位于 src/ 目录下，核心模块包括：

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[裁剪与缩放]

系统架构图

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

#### 支持的图像模型

资料来源：README.md

#### 输入参数

资料来源：README.md

#### 使用场景

文本生成图像：

{
  "prompt": "A modern dashboard UI with dark theme and blue accent colours",
  "aspectRatio": "16:9",
  "resolution": "2K",
  "filename": "dashboard-hero"
}

图像编辑（多轮对话）：

{
  "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

#### 功能列表

#### 输入参数

资料来源：README.md

#### 典型工作流

graph LR
    A[生成图像] --> B{主体颜色}
    B -->|红色/蓝色/黑色| C[绿幕生成]
    B -->|黄色/绿色/玻璃| D[画布方法]
    
    C --> E[色度键处理]
    E --> F[修边]
    F --> G[完成]
    
    D --> H[添加主体到背景]
    H --> G

配置管理

配置优先级

项目支持多层配置，按优先级从高到低排列：

graph TD
    A[环境变量] -->|最高| B[本地配置]
    B --> C[全局配置]
    C -->|最低| D[默认值]

优先级顺序：环境变量 > 本地配置（.gemini-image-mcp.json） > 全局配置（~/.gemini-image-mcp.json） > 默认值。 资料来源：README.md

环境变量

资料来源：README.md

配置文件格式

使用 --init 参数可生成带注释的配置文件模板：

npx @jimothy-snicket/gemini-image-mcp --init

配置文件示例（JSONC 格式，支持注释）：

{
  "defaultModel": "gemini-3.1-flash-image-preview",
  "defaults": {
    "generate": {
      "aspectRatio": "16:9",
      "resolution": "2K"
    },
    "process": {
      "removeBackground": { "color": "#00FF00" },
      "trim": true
    }
  }
}

安全特性

项目在配置管理中实现了多项安全措施：

资料来源：CHANGELOG.md

安装与部署

前置条件

安装步骤

使用 npm 安装：

npm install -g @jimothy-snicket/gemini-image-mcp

本地开发安装：

git clone https://github.com/JimothySnicket/gemini-image-mcp.git
cd gemini-image-mcp
bun install
bun run build

API 密钥配置

Windows (PowerShell)：

[System.Environment]::SetEnvironmentVariable('GEMINI_API_KEY', 'your-key-here', 'User')

macOS / Linux：

echo 'export GEMINI_API_KEY="your-key-here"' >> ~/.bashrc
source ~/.bashrc

MCP 客户端连接

项目支持多种 MCP 客户端连接方式：

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 中添加：

{
  "mcpServers": {
    "gemini-image": {
      "command": "npx",
      "args": ["@jimothy-snicket/gemini-image-mcp"]
    }
  }
}

资料来源：README.md

开发指南

本地开发

bun install        # 安装依赖
bun run dev        # 直接运行源代码
bun run build      # 编译 TypeScript 到 dist/

测试

运行测试需要设置 GEMINI_API_KEY 环境变量以测试实际的 Gemini API 调用。 资料来源：CONTRIBUTING.md

贡献指南

1. 先开 Issue：在编写代码之前，先描述 bug 或功能需求
2. 单一职责：每个 PR 只做一件事，不要捆绑不相关的更改
3. 构建检查：确保 bun run build 无错误通过
4. 手动测试：使用实际 Gemini API 测试更改
5. 保持精简：发现其他需要修复的问题时，单独开 Issue

版本历史

资料来源：CHANGELOG.md

许可证

本项目采用 MIT 许可证开源。 资料来源：README.md

系统概述

gemini-image-mcp 是一个基于 Model Context Protocol (MCP) 的服务器，为 Google Gemini 提供图像生成和本地处理能力。核心提供两个工具：

资料来源：README.md

快速安装

前置要求

• Node.js: >= 18.0.0
• 包管理器: npm、yarn 或 bun
• Gemini API 密钥: 从 Google AI Studio 获取

资料来源：package.json:22

安装命令

# 通过 npm 全局安装
npm install -g @jimothy-snicket/gemini-image-mcp

# 或使用 npx 直接运行（无需全局安装）
npx @jimothy-snicket/gemini-image-mcp

配置 API 密钥

服务器通过 GEMINI_API_KEY 环境变量读取你的密钥。

Windows (PowerShell)

[System.Environment]::SetEnvironmentVariable('GEMINI_API_KEY', 'your-key-here', 'User')

重启终端后生效。

资料来源：README.md

macOS / Linux

echo 'export GEMINI_API_KEY="your-key-here"' >> ~/.bashrc
source ~/.bashrc  # 或 source ~/.zshrc (zsh 用户)

验证配置

echo $GEMINI_API_KEY

如果输出你的密钥字符串，说明配置成功。

配置文件（可选）

除了环境变量，你还可以使用 JSON 配置文件进行更细粒度的控制：

npx @jimothy-snicket/gemini-image-mcp --init

此命令在 ~/.gemini-image-mcp.json 创建默认配置文件。

配置优先级

环境变量 > 本地配置文件 > 全局配置文件 > 默认值

资料来源：README.md

配置文件示例

{
  "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

Claude Desktop

编辑配置文件：

macOS/Linux:

~/.claude/desktops.json

Windows:

%APPDATA%\claude\desktops.json

配置内容：

{
  "mcpServers": {
    "gemini-image": {
      "command": "npx",
      "args": ["@jimothy-snicket/gemini-image-mcp"]
    }
  }
}

通用 MCP 客户端

{
  "mcpServers": {
    "gemini-image": {
      "command": "npx",
      "args": ["@jimothy-snicket/gemini-image-mcp"],
      "env": {
        "GEMINI_API_KEY": "your-api-key-here"
      }
    }
  }
}

核心工具使用

generate_image — AI 图像生成

#### 参数说明

资料来源：src/index.ts

#### 可用模型

资料来源：README.md

#### 使用示例

文本生成：

{
  "prompt": "A modern dashboard UI with dark theme and blue accent colours",
  "aspectRatio": "16:9",
  "resolution": "2K",
  "filename": "dashboard-hero",
  "subfolder": "landing-page"
}

图像编辑：

{
  "prompt": "Change the background to a sunset over water",
  "images": ["./src/assets/hero.png"],
  "aspectRatio": "16:9"
}

process_image — 本地图像处理

#### 参数说明

资料来源：src/index.ts

#### 使用示例

去除白色背景：

{
  "imagePath": "./product.png",
  "removeBackground": {"threshold": 230},
  "trim": true,
  "filename": "product-transparent"
}

绿幕抠像（两步流程）：

// 步骤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"
}

焦点裁剪：

{
  "imagePath": "./photo.png",
  "crop": {"aspectRatio": "16:9", "strategy": "attention"},
  "filename": "hero-banner"
}

工作流程图

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

成本控制与速率限制

环境变量配置

# 每小时最大请求数
export MAX_REQUESTS_PER_HOUR=20

# 每小时最大成本（美元）
export MAX_COST_PER_HOUR=5

安全特性

• API 密钥不接受配置文件（防止意外提交）
• 配置深度合并时防护原型污染攻击
• 未知配置项会警告并丢弃

资料来源：CHANGELOG.md

输出管理

文件命名

• 指定文件名时自动添加扩展名
• 文件名冲突时自动版本化：hero.png → hero-v2.png → hero-v3.png

子目录组织

{
  "filename": "hero",
  "subfolder": "landing-page"
}

输出路径：~/gemini-images/landing-page/hero.png

生成日志

每次生成自动追加到 generations.jsonl，记录：

• 提示词
• 参数
• 模型
• 成本
• 输出路径

资料来源：CHANGELOG.md

开发与调试

本地开发

# 安装依赖
bun install  # 或 npm install

# TypeScript 编译
bun run build

# 直接运行源码
bun run dev

资料来源：CONTRIBUTING.md

测试

测试图像生成需要设置 GEMINI_API_KEY 环境变量，详见 README。

故障排除

资料来源：src/generate.ts

下一步

• 查看 SKILL.md 了解高级提示技巧
• 阅读完整 README.md 获取详细功能说明
• 查看 CHANGELOG.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

核心依赖

资料来源：package.json:16-32

MCP 工具接口

工具注册架构

MCP 服务器通过 @modelcontextprotocol/sdk 定义并注册工具。每个工具包含参数模式（基于 Zod schema）和异步处理函数。

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 图像生成工具，支持文本生成图像和多轮编辑会话。

参数模型：

资料来源：src/index.ts:80-150

process_image 工具

process_image 提供本地图像处理功能，完全免费且无需 API 调用。

参数模型：

资料来源：src/index.ts:200-280

图像生成流程

完整生成流程

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

模型发现机制

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[返回可用模型列表]

项目支持的模型：

资料来源：src/generate.ts:50-80

配置系统

配置加载优先级

graph LR
    A[环境变量] -->|最高| Z[最终配置]
    B[本地配置<br/>.gemini-image-mcp.json] -->|次高| Z
    C[全局配置<br/>~/.gemini-image-mcp.json] -->|次低| Z
    D[代码默认值] -->|最低| Z

配置项说明：

资料来源：src/index.ts:300-350

配置文件格式

{
  // 默认模型
  "defaultModel": "gemini-3.1-flash-image-preview",
  // 各工具默认参数
  "defaults": {
    "generate": {
      "aspectRatio": "16:9",
      "resolution": "2K"
    },
    "process": {
      "removeBackground": { "color": "#00FF00" },
      "trim": true
    }
  }
}

资料来源：README.md:100-120

数据模型

图像生成响应

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

图像处理管道

graph LR
    A[输入图像] --> B[removeBackground]
    B --> C[trim]
    C --> D[crop]
    D --> E[resize]
    E --> F[format]
    F --> G[输出图像]
    
    H[quality 控制] -.-> F

处理操作支持链式调用，可在单次调用中完成背景移除、裁剪、缩放、格式转换等操作。

会话管理

多轮编辑架构

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

速率限制

限制机制

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 代理在循环中过度消耗资源。

项目入口点

启动方式：

# 开发模式（使用 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 声明其元数据：

{
  "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

安全性特性

配置系统实现的安全措施：

资料来源：CHANGELOG.md:10-25

总结

gemini-image-mcp 采用清晰的分层架构：

1. 协议层：基于 MCP SDK 实现标准化工具接口
2. 工具层：定义 generate_image 和 process_image 两个核心工具
3. 业务层：封装图像生成和处理的业务逻辑
4. 集成层：通过 @google/genai 连接 Gemini API，通过 sharp 实现本地处理
5. 配置层：统一的配置加载系统，支持多优先级配置源

该架构使项目能够灵活支持多种 MCP 客户端，同时保持核心逻辑的独立性和可测试性。

概述

gemini-image-mcp 是一个基于 Google Gemini API 的 MCP（Model Context Protocol）服务器，专门用于图像生成、编辑和本地处理。该项目采用 TypeScript 开发，支持双工具架构：AI 驱动的 generate_image 和本地免费的 process_image。

项目核心模块包括配置管理、图像生成、图像处理、令牌追踪、定价计算和工具函数六大模块，它们协同工作以提供完整的图像生成和处理解决方案。

架构概览

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]

模块依赖关系

详细模块分析

1. 配置模块（config.ts）

#### 功能职责

配置模块负责集中管理所有配置参数，支持多层级配置优先级和 JSONC 格式解析。

#### 配置优先级

graph LR
    A[环境变量] --> B[最高优先级]
    C[本地配置 .gemini-image-mcp.json] --> D[中等优先级]
    E[全局配置 ~/.gemini-image-mcp.json] --> F[最低优先级]
    G[代码默认值] --> F

#### 支持的配置项

#### JSONC 解析特性

• 支持字符串内嵌注释（不会破坏 URL）
• 自动移除尾部逗号
• 原型污染防护（__proto__, constructor, prototype）
• 未知配置键警告并丢弃

资料来源：src/config.ts

2. 图像生成模块（generate.ts）

#### 功能职责

图像生成模块是与 Gemini API 交互的核心，负责发送请求、处理响应、管理会话和处理错误。

#### 核心参数

#### 支持的模型

#### 会话管理流程

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 调用。

#### 处理能力

#### 焦点裁剪策略

#### 色度键处理流程

graph TD
    A[输入图像] --> B[HSV 颜色空间转换]
    B --> C[绿色范围检测]
    C --> D[Smoothstep 羽化]
    D --> E[溢出色抑制]
    E --> F[5次 3x3 边缘抗锯齿]
    F --> G[Alpha 通道合成]
    G --> H[输出透明背景图像]

#### 常见处理管道

// 从绿幕生成透明资产
{
  "imagePath": "./product-green.png",
  "removeBackground": {"color": "#00FF00"},
  "trim": true,
  "filename": "product-transparent"
}

// 社交卡片
{
  "imagePath": "./photo.png",
  "crop": {"aspectRatio": "16:9", "strategy": "attention"},
  "resize": {"width": 1200}
}

资料来源：src/process.ts

4. 追踪模块（tracker.ts）

#### 功能职责

追踪模块记录每次生成的详细信息，维护会话统计和生成清单。

#### 追踪数据结构

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;
  };
}

#### 会话统计

#### 速率限制

追踪器实时监控以下限制：

• MAX_REQUESTS_PER_HOUR：每小时最大请求数
• MAX_COST_PER_HOUR：每小时最大成本

超出限制时返回明确的错误信息和剩余配额。

资料来源：src/tracker.ts

5. 定价模块（pricing.ts）

#### 功能职责

计算每次 API 调用的成本，提供实时成本报告。

#### 价格表

#### 成本计算流程

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）

#### 功能职责

提供通用工具函数，支持其他核心模块的日常操作。

#### 主要工具函数

#### 文件命名规则

• 用户指定名称直接使用（无扩展名，自动添加）
• 重复文件名自动添加版本后缀：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

数据流图

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 是 gemini-image-mcp MCP 服务器提供的 AI 驱动的图像生成与编辑工具，基于 Google Gemini 原生 generateContent API 构建。该工具支持文生图、图像编辑、多轮对话式迭代优化等功能，是从 Google 即将废弃的 Imagen API 迁移的最佳选择。

资料来源：README.md

核心功能

文生图（Text-to-Image）

用户通过文本描述指定想要的图像内容，工具自动调用 Gemini 模型生成对应图像。

{
  "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

图像编辑（Image Editing）

支持传入参考图像，结合编辑指令对图像进行修改或重构。

{
  "prompt": "Change the background to a sunset over water",
  "images": ["./src/assets/hero.png"],
  "aspectRatio": "16:9"
}

资料来源：skills/image-generation/SKILL.md

多轮对话迭代

通过 sessionId 参数维持会话上下文，支持对图像进行多轮精细调整。每次对话都会保留对话历史，模型能够理解之前的生成结果并进行针对性修改。

{
  "prompt": "Make the colours warmer and add more contrast",
  "sessionId": "session-1711929600000-a1b2c3"
}

资料来源：skills/image-generation/SKILL.md

参数详解

请求参数

资料来源：README.md

返回结构

资料来源：src/index.ts

支持的模型

资料来源：README.md

架构设计

整体流程

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 可用的图像生成模型：

const IMAGE_MODEL_PATTERNS = ["image", "img"];
const EXCLUDED_PREFIXES = ["imagen"];

资料来源：src/generate.ts:100-104

Google Search Grounding 验证

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

多轮会话管理

会话数据结构

interface ConversationSession {
  history: Content[];
  model: string;
  lastAccessed: number;
}

会话限制

资料来源：src/generate.ts:136-145

会话生命周期

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[返回错误: 会话不存在或已过期]

会话清理机制

服务器定期清理过期会话，避免内存泄漏：

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

图像输入处理

支持的格式

文件大小限制

最大支持 50MB 的图像文件：

const MAX_IMAGE_SIZE = 50 * 1024 * 1024; // 50MB

资料来源：src/generate.ts:129-138

错误处理

如果图像格式不支持，将抛出详细错误信息：

throw new Error(
  `Unsupported image format "${ext}" for file: ${filepath}. ` +
    `Supported: ${Object.keys(MIME_TYPES).join(", ")}`,
);

资料来源：src/generate.ts:122-127

成本控制

速率限制

可通过环境变量配置每小时请求数和费用上限：

资料来源：README.md

费用报告

每次响应都包含详细费用信息：

{
  "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. 默认值 - 代码中的默认配置

配置文件示例

{
  "defaultModel": "gemini-3.1-flash-image-preview",
  "defaults": {
    "generate": {
      "aspectRatio": "16:9",
      "resolution": "2K"
    }
  },
  "maxRequestsPerHour": 20,
  "maxCostPerHour": 5
}

资料来源：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 日志文件：

{"prompt": "...", "model": "...", "cost": 0.04, "path": "...", "timestamp": "..."}

最佳实践

提示词结构

建议按照以下格式构建提示词：

[风格] [主体] [构图] [氛围/背景]

示例："A photorealistic product shot of headphones on marble, 4K, studio lighting, centered"

种子复现

使用 seed 参数确保相同输入产生相同输出：

{
  "prompt": "A blue rubber duck",
  "seed": 42
}

图像编辑建议

• 使用 sessionId 进行迭代优化，而非将输出图像作为新输入传回
• 会话保留对话上下文，生成效果更一致
• 模型失配检测会阻止使用不同模型继续同一会话

技术栈

资料来源：package.json

核心特性概览

资料来源：README.md

架构设计

模块依赖

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

处理流程

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[返回结果]

参数详解

必选参数

资料来源：src/index.ts

可选参数

#### 裁剪选项 (crop)

// 像素精确裁剪
{"width": 500, "height": 300, "left": 100, "top": 50}

// 宽高比裁剪 (中心裁剪)
{"aspectRatio": "16:9"}

// 焦点裁剪
{"aspectRatio": "16:9", "strategy": "attention"}
{"aspectRatio": "16:9", "strategy": "entropy"}

#### 缩放选项 (resize)

// 仅指定宽度
{"width": 1200}

// 仅指定高度
{"height": 800}

// 同时指定 (保持宽高比)
{"width": 1200, "height": 800}

#### 背景移除选项 (removeBackground)

// 阈值处理 (白色背景)
{"threshold": 230}

// 色度键控 (绿幕)
{"color": "#00FF00"}

// 色度键控 (任意颜色)
{"color": "#FF0000"}

#### 输出选项

资料来源：README.md, src/index.ts

色度键控技术

HSV 色彩空间键控

色度键控（Chroma Key）功能采用 HSV 颜色空间进行背景识别，相比 RGB 空间具有更好的光照适应性。

graph TD
    A[输入图像] --> B[转换到 HSV 色彩空间]
    B --> C[计算色相差异]
    C --> D[生成 Alpha 蒙版]
    D --> E[Smoothstep 羽化]
    E --> F[溢出色抑制]
    F --> G[5x5 边缘抗锯齿]
    G --> H[输出带透明通道图像]

处理阶段

资料来源：README.md

使用场景

// 高对比度主体的两步流程
// 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 (项目目录)

{
  "defaults": {
    "process": {
      "removeBackground": {"color": "#00FF00"},
      "trim": true
    }
  }
}

配置优先级：请求参数 > 本地配置 > 全局配置 > 默认值

资料来源：README.md

输出目录解析

输出目录的优先级顺序为：

graph TD
    A[outputDir 参数] --> B{存在?}
    B -->|是| C[使用参数值]
    B -->|否| D[outputDir 配置?]
    D -->|是| E[使用配置值]
    D -->|否| F[OUTPUT_DIR 环境变量?]
    F -->|是| G[使用环境变量]
    F -->|否| H[~/gemini-images 默认目录]

典型使用场景

场景一：Favicon 生成

{
  "imagePath": "./logo.png",
  "removeBackground": {"threshold": 230},
  "trim": true,
  "resize": {"width": 192, "height": 192},
  "filename": "favicon-192"
}

场景二：社交媒体卡片

{
  "imagePath": "./photo.png",
  "crop": {"aspectRatio": "16:9", "strategy": "attention"},
  "resize": {"width": 1200}
}

场景三：WebP 格式转换

{
  "imagePath": "./banner.png",
  "format": "webp",
  "quality": 85
}

场景四：透明资产流水线

graph LR
    A[generate_image<br/>绿幕产品图] --> B[process_image<br/>色度键控]
    B --> C[process_image<br/>trim 去白边]
    C --> D[process_image<br/>resize 调整尺寸]
    D --> E[最终透明 PNG]

// 完整流水线
[
  {"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

技术实现

依赖关系

// package.json 中的相关依赖
{
  "dependencies": {
    "sharp": "^0.34.5",
    "zod": "^3.24.0"
  }
}

资料来源：package.json

错误处理

工具在以下情况会抛出错误：

与 generate_image 的对比

推荐流程：generate_image 生成 → process_image 精修

资料来源：README.md, skills/image-generation/SKILL.md

概述

gemini-image-mcp 提供了一套集中化的配置管理系统，用于管理 MCP 服务器的各项运行时参数。该系统支持多种配置来源，包括环境变量、JSON 配置文件，并实现了明确的优先级覆盖机制。资料来源：src/config.ts:1-50

配置系统的主要职责包括：

• 配置加载：从多个来源加载配置并合并
• JSONC 解析：支持带注释的 JSON 配置文件
• 深度合并：将多个配置源合并为最终配置
• 参数验证：确保配置值的有效性和安全性
• 缓存机制：避免重复的文件 I/O 操作

配置优先级

系统采用明确的优先级层次，从高到低依次为：

环境变量 > 本地配置 > 全局配置 > 默认值

资料来源：README.md:设置

优先级层次详解

当多个配置源包含相同键时，优先级较高的配置源将覆盖优先级较低的配置源。资料来源：src/config.ts:100-120

配置文件

初始化配置文件

通过命令行可以快速生成配置文件模板：

# 创建全局配置文件
npx @jimothy-snicket/gemini-image-mcp --init

# 创建项目本地配置文件
npx @jimothy-snicket/gemini-image-mcp --init --local

资料来源：README.md:#setup

配置文件格式

配置文件使用 JSONC 格式（带注释的 JSON），允许在配置文件中添加内联注释：

{
  // 默认模型设置
  "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

配置结构

完整配置对象

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

生成工具默认值

interface GenerateDefaults {
  model?: string;
  aspectRatio?: string;
  resolution?: string;
  useSearchGrounding?: boolean;
}

处理工具默认值

interface ProcessDefaults {
  removeBackground?: RemoveBackgroundOptions;
  trim?: boolean;
  format?: "png" | "jpeg" | "webp";
  quality?: number;
}

资料来源：src/config.ts:37-50

环境变量

支持的环境变量

资料来源：CHANGELOG.md:0.3.0 Changed 和 src/config.ts:50-80

API 密钥配置

重要安全提示：API 密钥不应存储在配置文件中，因为配置文件可能被提交到代码仓库。

# 正确的做法：使用环境变量
export GEMINI_API_KEY="your-key-here"

# 配置文件中的 API 密钥会被警告并拒绝

资料来源：CHANGELOG.md:Security

配置加载流程

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

深度合并策略

配置系统使用深度合并算法，将多个配置源合并为单一配置对象：

deepMerge(target: Record<string, any>, source: Record<string, any>): Record<string, any>

合并规则：

• 数组覆盖：源数组完全替换目标数组（非合并）
• 对象递归：嵌套对象递归合并
• 原类型保留：保持目标值的原始类型

资料来源：src/config.test.ts:100-150

安全机制

原型污染防护

配置系统实现了原型污染攻击防护，检查以下危险键：

• __proto__
• constructor
• prototype

// 示例：以下配置将被拒绝
{
  "__proto__": { "isAdmin": true },
  "constructor": { "prototype": { "malicious": true } }
}

资料来源：CHANGELOG.md:Security

API 密钥保护

配置文件中的 API 密钥会被检测并警告：

[安全警告] 配置文件中的 API 密钥已被拒绝。请使用环境变量 GEMINI_API_KEY

资料来源：src/config.ts:150-180

JSONC 注释解析安全

字符串中包含的 URL 或 JSON 片段不会被误解析为注释：

{
  "url": "https://example.com/api?key=abc123",  // 注释
  "data": "{\"key\": \"value\"}"                  // 这是字符串，不是 JSON
}

资料来源：CHANGELOG.md:Security

配置验证

模型验证

系统在启动时会验证 API 密钥并自动发现可用的图像生成模型：

async autoDiscoverModels(): Promise<string[]>

发现过程：

1. 调用 Gemini API 列出可用模型
2. 过滤掉 Imagen 模型（已于 2026 年 6 月废弃）
3. 返回支持图像生成的模型列表

资料来源：CHANGELOG.md:Added

参数验证

使用 Zod 进行运行时参数验证：

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：

{
  "outputDir": "~/gemini-images",
  "defaultModel": "gemini-3.1-flash-image-preview",
  "logLevel": "info"
}

工具默认值配置

{
  "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

速率限制配置

# 设置每小时最多 20 次请求
export MAX_REQUESTS_PER_HOUR=20

# 设置每小时最大成本 5 美元
export MAX_COST_PER_HOUR=5

{
  "maxRequestsPerHour": 20,
  "maxCostPerHour": 5
}

资料来源：README.md:Rate limiting

调试配置

日志级别

export LOG_LEVEL=debug

请求超时

# 设置 120 秒超时
export REQUEST_TIMEOUT_MS=120000

{
  "requestTimeoutMs": 120000
}

常见问题

Q: 配置文件修改后需要重启吗？

是的。配置在服务器启动时加载，修改配置文件后需要重启 MCP 服务器。

Q: 如何查看当前生效的配置？

目前没有命令直接查看合并后的配置。可通过检查各配置源文件来确认配置状态。

Q: 为什么不支持从配置文件读取 API 密钥？

出于安全考虑。配置文件可能被提交到版本控制系统（如 Git），导致密钥泄露。

Q: 如何重置为默认配置？

删除配置文件并重新初始化：

rm ~/.gemini-image-mcp.json
npx @jimothy-snicket/gemini-image-mcp --init

变更历史

资料来源：CHANGELOG.md

概述

gemini-image-mcp 是一个基于 Model Context Protocol (MCP) 的服务器，为 AI 图像生成和处理提供标准化的工具接口。该项目通过 MCP 协议与各种 AI 客户端集成，支持文本到图像生成、图像编辑、本地图像处理等功能。

核心项目括：

• generate_image — 调用 Google Gemini API 生成或编辑图像
• process_image — 本地图像处理（裁剪、缩放、背景移除等），无需 API 调用

资料来源：README.md:1-15

部署架构

系统组件

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 客户端通信，支持两种启动方式：

资料来源：package.json:1-20 资料来源：CONTRIBUTING.md:1-15

环境配置

API 密钥设置

服务器需要 GEMINI_API_KEY 环境变量才能正常启动。密钥必须从 Google AI Studio 获取。

Windows (PowerShell):

[System.Environment]::SetEnvironmentVariable('GEMINI_API_KEY', 'your-key-here', 'User')

macOS / Linux:

echo 'export GEMINI_API_KEY="your-key-here"' >> ~/.bashrc
source ~/.bashrc

验证配置：

echo $GEMINI_API_KEY

资料来源：README.md:30-50

配置文件

除了环境变量，还支持 JSON 配置文件方式。初始化配置文件：

npx @jimothy-snicket/gemini-image-mcp --init

此命令在用户主目录创建 ~/.gemini-image-mcp.json，包含所有可配置项及说明文档。

配置优先级：

环境变量 > 本地配置 (.gemini-image-mcp.json) > 全局配置 (~/.gemini-image-mcp.json) > 默认值

配置文件结构：

资料来源：README.md:80-115

MCP 服务器配置

server.json 清单

每个 MCP 服务器需要通过 server.json 声明其元数据。gemini-image-mcp 的配置如下：

{
  "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
    }]
  }]
}

关键配置说明：

资料来源：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 工具

技能使用示例：

{
  "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 配置中添加服务器：

{
  "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 兼容客户端，配置格式类似：

{
  "mcpServers": {
    "gemini-image-mcp": {
      "command": "bun",
      "args": ["path/to/dist/index.js"],
      "env": {
        "GEMINI_API_KEY": "your-api-key"
      }
    }
  }
}

构建用于生产部署：

bun install
bun run build

资料来源：CONTRIBUTING.md:8-12

工具接口

generate_image

通过 Gemini API 生成或编辑图像。

资料来源：src/index.ts:40-100

process_image

本地图像处理，无需 API 调用。

资料来源：README.md:95-120

可用模型

服务器启动时自动发现可用的图像模型，验证 API 密钥有效性。

资料来源：README.md:130-140

速率限制

生产环境中使用速率限制防止成本失控：

推荐配置：

MAX_REQUESTS_PER_HOUR=20
MAX_COST_PER_HOUR=5

速率超限返回明确错误，包含剩余预算信息。Agent 循环使用时应配置这些限制。

资料来源：README.md:75-80

开发与调试

本地开发环境

bun install      # 安装依赖
bun run build    # TypeScript 编译到 dist/
bun run dev      # 直接运行源码（热重载）

需要设置 GEMINI_API_KEY 环境变量用于测试图像生成。

日志级别

通过 LOG_LEVEL 环境变量控制日志详细程度：

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 或各自密钥。

{
  "defaultModel": "gemini-3.1-flash-image-preview",
  "maxCostPerHour": 10,
  "outputDir": "~/team-gemini-images"
}

场景三：CI/CD 集成

在自动化流程中使用时，确保：

1. 环境变量正确注入
2. 速率限制已配置
3. 输出目录已创建
4. 网络可访问 Gemini API

# CI 配置示例
env:
  GEMINI_API_KEY: ${{ secrets.GEMINI_API_KEY }}
  MAX_COST_PER_HOUR: 2
  LOG_LEVEL: info

概述

gemini-image-mcp 提供了完整的成本追踪和速率限制机制，用于监控 API 使用情况并防止意外超支。这两个功能相互配合，确保用户在调用 Gemini 图像生成 API 时能够清晰了解费用并控制支出。

核心功能

资料来源：README.md

概述

gemini-image-mcp 项目支持多个 Google Gemini 图像生成模型，每个模型在速度、成本、质量和功能方面各有侧重。开发者需要根据具体使用场景选择合适的模型，以达到最佳效果与成本平衡。

项目使用 @google/genai 库（版本 ^1.44.0）与 Gemini API 进行交互，通过 MCP（Model Context Protocol）协议提供服务。资料来源：package.json:1-25

支持的模型列表

模型对比总览

资料来源：README.md:1-45

模型选择流程

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 超高清输出的项目

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

模型选择指南

按使用场景选择

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-image-mcp.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 调用示例

指定模型生成图像：

{
  "prompt": "A photorealistic product shot of headphones on marble, 4K",
  "model": "gemini-3-pro-image-preview",
  "aspectRatio": "16:9",
  "resolution": "4K"
}

使用 Search Grounding：

{
  "prompt": "Generate an infographic about the latest iPhone model",
  "model": "gemini-3.1-flash-image-preview",
  "useSearchGrounding": true
}

成本管理

速率限制配置

项目支持按小时设置请求和成本上限，防止意外超支：

建议在自动化代理场景中设置这些限制：

export MAX_REQUESTS_PER_HOUR=20
export MAX_COST_PER_HOUR=5

资料来源：README.md:60-75

成本计算

每次生成图像后，API 响应中包含详细的用量信息：

{
  "usage": {
    "promptTokens": 5,
    "outputTokens": 1295,
    "imageTokens": 1290,
    "thinkingTokens": 412,
    "totalTokens": 1712,
    "estimatedCost": "$0.0390"
  },
  "session": {
    "totalCostThisSession": "$0.1161",
    "remainingThisHour": 15
  }
}

资料来源：README.md:50-65

模型演进与迁移

版本时间线

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

总结与建议

快速参考表

最佳实践

1. 开发阶段：使用 gemini-2.5-flash-image 快速迭代
2. 预生产：切换到 gemini-3.1-flash-image-preview 验证质量
3. 正式发布：使用 gemini-3-pro-image-preview 确保最佳效果
4. 成本监控：始终关注 remainingThisHour 和 estimatedCost 字段

通过合理选择模型，开发者可以在项目不同阶段实现成本与质量的最优平衡。

Pitfall Log / 踩坑日志

项目：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