金大哥 - gemini-2.5-flash-image-mcp MCP 详情

article

README

🚀 Gemini 2.5 Flash Image MCP

Gemini 2.5 Flash Image MCP 是一个模型上下文协议（MCP）服务器，可借助 Google 的 Gemini 2.5 Flash Image 预览版进行对话式图像生成与编辑。它易于安装，可通过 Claude Code 及其他 MCP 客户端使用。

✨ 主要特性

文本到图像：根据详细提示词生成图像
图像编辑：使用自然语言指令编辑图像
多图像合成/风格迁移：组合图像或迁移风格
文件保存选项：返回 base64 格式图像，并可选择保存到文件
与供应商无关的 MCP：可在任何支持 MCP 的客户端中使用

📦 安装指南

系统要求

Node.js 18 或更高版本
一个 MCP 客户端（Claude Code、Cursor、VS Code、Windsurf 等）
Google Gemini API 密钥：设置 GEMINI_API_KEY

获取 Gemini API 密钥

按照以下步骤从 Google AI Studio 获取 API 密钥：

打开 Google AI Studio 并登录：https://aistudio.google.com/apikey
点击“创建 API 密钥”（若已有密钥则点击“管理密钥”）
复制生成的密钥
在运行此服务器时，将其设置为机器上的环境变量

示例：

# macOS / Linux (bash/zsh)
export GEMINI_API_KEY="YOUR_API_KEY"

# Windows PowerShell
$env:GEMINI_API_KEY="YOUR_API_KEY"

🚀 快速开始

首先，将 MCP 服务器与你的客户端进行安装。以下示例以 Claude Code 的使用为主。

标准配置

标准配置适用于大多数工具：

{
  "mcpServers": {
    "gemini-2-5-flash-mcp": {
      "command": "npx",
      "args": ["@taiyokimura/gemini-2-5-flash-mcp@latest"]
    }
  }
}

快速使用（Claude Code）

# npx（带非交互标志）+ 同时指定 API 密钥（Claude 的 -e 指定）
claude mcp add gemini-2-5-flash-mcp -s user -e GEMINI_API_KEY="YOUR_API_KEY" -- npx -y @taiyokimura/gemini-2-5-flash-mcp@latest

# 全局安装 + 同时指定 API 密钥（Claude 的 -e 指定）
npm i -g @taiyokimura/gemini-2-5-flash-mcp \
  && claude mcp add gemini-2-5-flash-mcp -s user -e GEMINI_API_KEY="YOUR_API_KEY" -- gemini-2-5-flash-mcp

# HTTP 模式注册示例（SSE 为默认）（仅适用于支持的客户端）
# ※ HTTP 模式下，此进程将作为 HTTP 服务器常驻
claude mcp add gemini-2-5-flash-mcp -s user \
  -e GEMINI_API_KEY="YOUR_API_KEY" \
  -e MCP_TRANSPORT="http" \
  -e MCP_HTTP_PORT="7801" \
  -e MCP_HTTP_PATH="/mcp" \
  -- npx -y @taiyokimura/gemini-2-5-flash-mcp@latest

可流式传输的 HTTP 模式（实验性）

也可以使用可流式传输的 HTTP 代替 STDIO。仅在 MCP 客户端支持可流式传输的 HTTP 时使用。

以 HTTP 模式启动服务器

export MCP_TRANSPORT=http
export GEMINI_API_KEY=YOUR_API_KEY
# 可选（默认值: 7801, /mcp, SSE）
export MCP_HTTP_PORT=7801
export MCP_HTTP_PATH=/mcp
export MCP_HTTP_ENABLE_JSON=false

npm run build
node ./build/index.js
# => HTTP 传输监听地址：http://localhost:7801/mcp

客户端配置（示例：支持可流式传输的 HTTP 的客户端）

类型：HTTP (可流式传输)
URL：http://localhost:7801/mcp

注：

SSE 流式传输为默认设置。若要使用 JSON 响应，请设置 MCP_HTTP_ENABLE_JSON=true。
会话在服务器端生成（有状态）。若要实现完全无状态，可在代码中将 sessionIdGenerator: undefined 进行修改。

Claude Code（推荐）

使用 Claude Code CLI 添加 MCP 服务器：

claude mcp add gemini-2-5-flash-mcp -s user -- npx @taiyokimura/gemini-2-5-flash-mcp@latest

如有需要，可进行移除：

claude mcp remove gemini-2-5-flash-mcp

Claude Desktop

遵循 MCP 安装指南并使用上述标准配置。

指南：https://modelcontextprotocol.io/quickstart/user

Cursor

前往 Cursor 设置 → MCP → 添加新的 MCP 服务器。

使用以下设置：

名称：gemini-2-5-flash-mcp
类型：命令
命令：npx
参数：@taiyokimura/gemini-2-5-flash-mcp@latest
自动启动：开启（可选）

VS Code

通过 CLI 添加：

code --add-mcp '{"name":"gemini-2-5-flash-mcp","command":"npx","args":["@taiyokimura/gemini-2-5-flash-mcp@latest"]}'

或在设置中使用标准配置。

LM Studio

添加 MCP 服务器，设置如下：

命令：npx
参数：["@taiyokimura/gemini-2-5-flash-mcp@latest"]

Goose

高级设置 → 扩展 → 添加自定义扩展：

类型：STDIO
命令：npx
参数：@taiyokimura/gemini-2-5-flash-mcp@latest
启用：是

opencode

示例 ~/.config/opencode/opencode.json：

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "gemini-2-5-flash-mcp": {
      "type": "本地",
      "命令": [
        "npx",
        "@taiyokimura/gemini-2-5-flash-mcp@latest"
      ],
      "启用": true
    }
  }
}

Qodo Gen

打开 Qodo Gen → 连接更多工具 → + 添加新的 MCP → 粘贴上述标准配置 → 保存。

Windsurf

遵循 Windsurf MCP 文档并使用上述标准配置。

文档：https://docs.windsurf.com/windsurf/cascade/mcp

📚 详细文档

环境变量

GEMINI_API_KEY（必需）
GEMINI_IMAGE_ENDPOINT（可选）默认值： https://generativelanguage.googleapis.com/v1beta/models/gemini-2.5-flash-image-preview:generateContent
MCP_NAME（可选，默认值：gemini-2-5-flash-mcp）

可用工具

1. generate_image

根据文本提示词生成图像。

参数：

prompt（必需）：用于生成图像的详细描述
saveToFilePath（可选）：保存图像的路径

示例输入：

{
  "prompt": "创建一张带有 Gemini 主题的高档餐厅里的纳米香蕉菜肴的图片",
  "saveToFilePath": "./gemini-native-image.png"
}

2. edit_image

使用提示词编辑图像。

参数：

prompt（必需）：编辑指令
image（必需）：{ dataBase64?: string, path?: string, mimeType?: string }
saveToFilePath（可选）

示例输入：

{
  "prompt": "给猫添加一顶小的针织巫师帽",
  "image": { "path": "./cat.jpeg", "mimeType": "image/jpeg" },
  "saveToFilePath": "./gemini-edited-image.png"
}

3. compose_images

组合多个图像的元素。

参数：

prompt（必需）
images（必需）：图像输入数组（建议 2 - 3 个）
saveToFilePath（可选）

4. style_transfer

将一个图像的风格迁移到另一个图像。

参数：

prompt（可选）
baseImage（必需）
styleImage（必需）
saveToFilePath（可选）

🔧 技术细节

本地运行

npm install
npm run build
npx .

名称一致性与故障排除

始终使用规范标识符（CANONICAL_ID）gemini-2-5-flash-mcp 作为标识符和键。
仅在 UI 标签中使用规范显示名称（CANONICAL_DISPLAY）Gemini 2.5 Flash MCP。
不要在不同客户端中混用不同名称。

一致性矩阵： | 属性 | 详情 | |------|------| | npm 包名 | gemini-2-5-flash-mcp | | 二进制名称 | gemini-2-5-flash-mcp | | MCP 服务器名称（SDK 元数据） | gemini-2-5-flash-mcp | | 环境默认 MCP_NAME | gemini-2-5-flash-mcp | | 客户端注册表键 | gemini-2-5-flash-mcp | | UI 标签 | Gemini 2.5 Flash MCP |

冲突清理：

删除任何旧的条目（如 "GeminiFlash"），并使用 gemini-2-5-flash-mcp 重新添加。
确保全局注册表仅使用 gemini-2-5-flash-mcp 作为键。
Cursor：仅在 UI 中进行配置。此项目不包含 .cursor/mcp.json。

📄 参考资料

MCP SDK：https://modelcontextprotocol.io/docs/sdks
架构：https://modelcontextprotocol.io/docs/learn/architecture
服务器概念：https://modelcontextprotocol.io/docs/learn/server-concepts
服务器规范（2025-06-18）：https://modelcontextprotocol.io/specification/2025-06-18/server/index
Gemini 图像生成：https://ai.google.dev/gemini-api/docs/image-generation

gemini-2.5-flash-image-mcp