使用说明

Gemini映像MCP服务器

A. 模型上下文协议（MCP）服务器，用于使用谷歌的Gemini AI模型生成和编辑图像。提供两个工具，任何MCP客户端都可以使用这两个工具从文本描述中创建图像，并使用自然语言指令修改现有图像。

特性

14宽高比 通过Gemini的原生支持 imageConfig: 1:1, 1:4, 1:8, 2:3, 3:2, 3:4, 4:1, 4:3, 4:5, 5:4, 8:1, 9:16, 16:9, 21:9
4个分辨率级别: 512 （仅适用于Flash型号）， 1K, 2K, 4K
多种Gemini型号: gemini-3-pro-image-preview （高保真、准确的文本）和 gemini-3.1-flash-image-preview （快速、经济高效），接受任何型号字符串
图像编辑：使用自然语言指令修改现有图像，包括更改纵横比
参考图像：提供上下文图像以指导生成风格和构图
水印：用可配置的定位覆盖品牌徽标或水印
包含CLI：用于终端工作流的独立命令行界面
MCP+标准传输：适用于任何MCP客户端（Claude Desktop、Claude Code、VS Code、Cursor等）

快速开始

先决条件

需要Google AI API密钥。免费获得一个谷歌人工智能工作室.

安装并运行

npx gemini-image-mcp-server

或全局安装：

npm install -g gemini-image-mcp-server

安装

在MCP客户端中配置服务器。服务器通过stdio进行通信。

Claude Desktop

添加到您的 claude_desktop_config.json:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json 视窗: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "gemini-image": {
      "command": "npx",
      "args": ["-y", "gemini-image-mcp-server"],
      "env": {
        "GOOGLE_API_KEY": "your-api-key-here"
      }
    }
  }
}

Claude Code

claude mcp add gemini-image -- npx -y gemini-image-mcp-server

然后在环境中或您的 .claude/settings.json:

{
  "mcpServers": {
    "gemini-image": {
      "command": "npx",
      "args": ["-y", "gemini-image-mcp-server"],
      "env": {
        "GOOGLE_API_KEY": "your-api-key-here"
      }
    }
  }
}

VS Code (Copilot)

添加到您的VS代码 settings.json:

{
  "mcp": {
    "servers": {
      "gemini-image": {
        "command": "npx",
        "args": ["-y", "gemini-image-mcp-server"],
        "env": {
          "GOOGLE_API_KEY": "your-api-key-here"
        }
      }
    }
  }
}

Cursor

添加到光标MCP配置中：

{
  "mcpServers": {
    "gemini-image": {
      "command": "npx",
      "args": ["-y", "gemini-image-mcp-server"],
      "env": {
        "GOOGLE_API_KEY": "your-api-key-here"
      }
    }
  }
}

From Source (all clients)

克隆并构建，然后将MCP客户端指向已编译的条目：

git clone https://github.com/amineew-cell/gemini-image-mcp-server.git
cd gemini-image-mcp-server
npm install
npm run build

在MCP客户端配置中使用：

{
  "mcpServers": {
    "gemini-image": {
      "command": "node",
      "args": ["/absolute/path/to/gemini-image-mcp-server/dist/index.js"],
      "env": {
        "GOOGLE_API_KEY": "your-api-key-here"
      }
    }
  }
}

配置

环境变量	必填	说明
`GOOGLE_API_KEY`	是	Google AI API密钥来自 AI 工作室

工具

`generate_image`

根据文本描述创建新图像。当您需要生成新鲜的视觉内容时，请使用此工具。

最适合：产品照片、插图、社交媒体图形、概念艺术、纹理、背景。

参数：

参数	类型	必填	默认	说明
`description`	string	是		要生成的图像的详细描述
`aspectRatio`	string	否	`1:1`	输出纵横比。什么之中的一个： `1:1`, `1:4`, `1:8`, `2:3`, `3:2`, `3:4`, `4:1`, `4:3`, `4:5`, `5:4`, `8:1`, `9:16`, `16:9`, `21:9`
`imageSize`	string	否	`1K`	分辨率级别。什么之中的一个： `512` （仅限Flash）， `1K`, `2K`, `4K`.必须大写K
`model`	string	否	`gemini-3-pro-image-preview`	Gemini型号ID。使用 `gemini-3.1-flash-image-preview` 为了更快、更便宜的发电。
`style`	string	否		风格提示（例如，“极简主义”、“水彩”、“照片级真实感”）
`images`	string[]	否		引导生成的参考图像的文件路径
`outputPath`	string	否	cwd	保存图像的位置。可以是目录或完整文件路径。
`watermarkPath`	string	否		要覆盖的水印图像的路径
`watermarkPosition`	string	否	`bottom-right`	水印角： `top-left`, `top-right`, `bottom-left`, `bottom-right`

退货： 保存图像的绝对文件路径。

示例工具调用：

{
  "name": "generate_image",
  "arguments": {
    "description": "A brown leather wallet on a white marble surface, overhead studio lighting, minimal composition",
    "aspectRatio": "4:5",
    "imageSize": "2K",
    "outputPath": "./images/wallet-hero.png"
  }
}

`edit_image`

使用自然语言指令修改现有图像。当您有图像并想要更改特定元素、调整构图或变换纵横比时，请使用此工具。

最适合：润饰、背景更改、添加/删除元素、根据不同宽高比重新组合、风格转换。

参数：

参数	类型	必填	默认	说明
`description`	string	是		描述要应用的编辑的说明
`image`	string	是		要编辑的源图像的路径
`aspectRatio`	string	否		输出纵横比。使用此选项可将图像重新组合为不同的格式（例如，从方形到纵向）。
`imageSize`	string	否		输出的解析层
`model`	string	否	`gemini-3-pro-image-preview`	Gemini型号ID
`outputPath`	string	否	cwd	编辑后的图像保存在哪里

退货： 保存的编辑图像的绝对文件路径。

示例工具调用：

{
  "name": "edit_image",
  "arguments": {
    "description": "Extend the background naturally to fill a taller portrait composition. Keep the subject centered.",
    "image": "./images/product-square.png",
    "aspectRatio": "4:5",
    "outputPath": "./images/product-portrait.png"
  }
}

在工具之间进行选择

场景	工具	为什么
从头开始创建图像	`generate_image`	不需要源图像
更改现有图像的纵横比	`edit_image`	在重新组合时保留内容
添加/删除照片中的元素	`edit_image`	修改特定零件
生成受参考启发的变体	`generate_image` 随着 `images`	使用参考作为风格指南，创建新内容
应用水印	`generate_image`	内置水印支持

用法示例

这些是您可以在任何MCP客户端上使用的自然语言提示：

为Instagram生成产品快照：

在木桌上用柔和的窗户光线生成一个皮革笔记本的图像。Instagram订阅源使用4:5的宽高比。

创建宽横幅：

使用笔和对开本创建全景极简主义工作空间场景。16:9比例，2K分辨率。

编辑现有图像：

编辑此图像：扩展背景，将其从方形更改为4:5肖像格式。保持主体居中，自然延伸背景。

使用参考图像生成：

生成一张受此参考图像启发的产品照片，但背景较暗，光线较暖。使用相同的构图风格。

高分辨率纹理：

使用温暖的定向照明生成皮革纹理的特写。方形格式，2K分辨率。

命令行界面

服务器包括一个用于终端工作流的独立CLI。

生成

gemini-image generate \
  --prompt "A leather wallet on white marble, studio lighting" \
  --aspect 4:5 \
  --size 2K \
  --output ./images/wallet.png

编辑

gemini-image edit \
  --prompt "Make the background darker and add warm highlights" \
  --input ./images/original.png \
  --aspect 4:5 \
  --output ./images/edited.png

所有CLI标志

生成命令：

标志	简短	描述
`--prompt`	`-p`	图像描述（必填）
`--aspect`	`-a`	纵横比（例如。， `4:5`, `16:9`).违约： `1:1`
`--size`	`-z`	图像大小： `512`, `1K`, `2K`, `4K`默认值： `1K`
`--model`	`-m`	Gemini型号ID
`--style`	`-s`	风格提示
`--context`	`-c`	参考图像路径（可重复）
`--output`	`-o`	输出路径
`--watermark`		水印图像路径
`--watermark-position`		水印角位置

编辑命令：

标志	简短	描述
`--prompt`	`-p`	编辑说明（必填）
`--input`	`-i`	源图像路径（必需）
`--aspect`	`-a`	输出纵横比
`--size`	`-z`	输出图像大小
`--model`	`-m`	Gemini型号ID
`--output`	`-o`	输出路径

可用模型

型号	最适合	备注
`gemini-3-pro-image-preview`	复杂的设计，高保真输出，图像中的文本准确	默认值。质量更高，速度更慢。
`gemini-3.1-flash-image-preview`	大批量生产，快速迭代，成本效益高	更快更便宜。支持 `512` 图像大小。

您可以通过以下方式传递任何有效的Gemini型号ID model 参数。

故障排除

“需要GOOGLE_API_KEY环境变量”

未设置API密钥。确保您的MCP客户端配置包括 env 堵塞 GOOGLE_API_KEY，或将其导出到shell中以供CLI使用。

“找不到型号/xxx”（404错误）

模型ID无效或无法用于API密钥。检查：

模型名称拼写正确（例如。， gemini-3-pro-image-preview，不 gemini-3-pro)
您的API密钥可以访问该模型（有些模型需要allowlisting）

图像的宽高比错误

验证您是否通过 aspectRatio 参数。如果省略，默认值为 1:1。该比率必须是14个支持值之一。

“双子座完成原因：安全”或空回答

提示或生成的内容触发了Gemini的安全过滤器。尝试：

重新表述提示，使其更具体，不那么含糊
使用不同的模型（Flash可能具有不同的过滤阈值）

图像文件未保存/权限错误

确保输出目录存在或服务器有权创建它
如果指定目录，请以 /
使用绝对路径以避免歧义

服务器未连接到MCP客户端

验证 command 和 args 客户端配置正确
检查一下 node 在你的路径中
查看stderr输出中的错误消息（服务器将日志记录到stderr）
试着跑步 npx gemini-image-mcp-server 直接验证它是否启动

发展

git clone https://github.com/amineew-cell/gemini-image-mcp-server.git
cd gemini-image-mcp-server
npm install
npm run build

看贡献.md 详细的开发指南。

许可证

阿帕奇-2.0

使用说明

Gemini映像MCP服务器

特性

快速开始

先决条件

安装并运行

安装

配置

工具

generate_image

edit_image

在工具之间进行选择

用法示例

命令行界面

生成

编辑

所有CLI标志

可用模型

故障排除

“需要GOOGLE_API_KEY环境变量”

“找不到型号/xxx”（404错误）

图像的宽高比错误

“双子座完成原因：安全”或空回答

图像文件未保存/权限错误

服务器未连接到MCP客户端

发展

许可证

相关 MCP

多模态生成API服务

图像生成服务

Hugging Face MCP服务器

LLM增强工具包

多模态AI生成服务器

图片处理服务器

`generate_image`

`edit_image`