Gemini 2.5 Flash Image MCP

🚀 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 密钥：

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

示例：

# 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 时使用。

1. 以 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

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

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

注：

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

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

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

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

📚 详细文档

环境变量

• 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。
• 不要在不同客户端中混用不同名称。

一致性矩阵：

冲突清理：

• 删除任何旧的条目（如 "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