项目简介

本项目是一个基于 Model Context Protocol (MCP) 的服务器实现，它利用 Google 的 Gemini 模型，为支持 MCP 协议的AI客户端（如 Claude、Cursor 等）提供强大的图像生成和图像编辑能力。通过简单的文本指令，AI助手即可调用此服务器生成全新的图像，或对现有图像进行编辑和变换。

主要功能点

文生图 (Text-to-Image)： 根据文本描述，生成全新的高质量图像。例如，您可以让AI助手生成“山脉日落的图像”或“未来城市的插画”。
图生图 (Image-to-Image) 变换： 基于文本指令，对已有的图像进行编辑和变换。支持两种方式上传图像：
- Base64 编码图像： 直接粘贴或上传 Base64 编码的图像数据。
- 本地文件路径： 提供服务器可访问的本地图像文件路径。
智能文件名生成： 根据用户输入的提示词，自动生成描述性的文件名，方便管理生成的图像。
多语言提示词支持与自动翻译： 支持非英语提示词，并自动翻译成英文以优化 Gemini 模型的生成效果。
本地图像存储： 生成的图像默认保存在服务器本地，并支持自定义输出路径。
无文本图像生成保证： 严格避免在生成的图像中出现任何文本，即使提示词中包含文本要求。
高分辨率图像输出： 生成高质量、高分辨率的图像。

安装步骤

环境准备：
- 确保已安装 Python 3.11 或更高版本。
- 拥有 Google AI API 密钥 (Gemini API Key)。如果您没有，请访问 Google AI Studio API Keys page 注册并创建。
- 准备好 MCP 客户端应用，例如 Claude Desktop App 或 Cursor。
获取 Gemini API 密钥：
- 访问 Google AI Studio API Keys page，登录您的 Google 账户。
- 点击 "Create API Key" 创建 API 密钥。
- 复制您的 API 密钥，后续配置需要使用。

克隆仓库： 在您的本地计算机上克隆此 GitHub 仓库：

git clone https://github.com/qhdrl12/mcp-server-gemini-image-generator.git
cd mcp-server-gemini-image-generator

创建虚拟环境并安装依赖： 使用 'venv' 或 'uv' 创建虚拟环境并安装项目依赖。

# 使用 venv
python -m venv .venv
source .venv/bin/activate  # 或 .venv\Scripts\activate (Windows)
pip install -e .

# 或使用 uv (更快速)
uv venv
source .venv/bin/activate  # 或 .venv\Scripts\activate (Windows)
uv pip install -e .

配置环境变量： 复制 '.env.example' 文件并重命名为 '.env'，然后编辑 '.env' 文件，填入您的 Gemini API 密钥和期望的图像输出路径。

cp .env.example .env

编辑 '.env' 文件，例如：

GEMINI_API_KEY="YOUR_GEMINI_API_KEY"  # 替换为您的 Gemini API 密钥
OUTPUT_IMAGE_PATH="/path/to/save/images" # 替换为您希望保存图像的路径，例如 "/Users/yourname/Pictures/generated_images"

服务器配置

要将此 MCP 服务器连接到 MCP 客户端（例如 Claude Desktop），您需要在客户端的配置文件中添加服务器配置信息。以 Claude Desktop 为例，编辑 'claude_desktop_config.json' 文件（macOS 路径通常为 '~/Library/Application Support/Claude/claude_desktop_config.json'）。

在 'claude_desktop_config.json' 文件的 'mcpServers' 字段下添加以下 JSON 配置：

{
    "mcpServers": {
        "gemini-image-generator": {  // 服务器名称，您可以自定义
            "command": "uv",  // 启动服务器的命令，如果使用 venv，则为 "python"
            "args": [
                "--directory",  // 指定工作目录参数
                "/absolute/path/to/gemini-image-generator",  //  替换为您的 gemini-image-generator 仓库的绝对路径，例如 "/Users/yourname/mcp-server-gemini-image-generator"
                "run",  // 运行命令
                "server.py" // 服务器启动脚本
            ],
            "env": {
                "GEMINI_API_KEY": "GEMINI_API_KEY",  //  将 GEMINI_API_KEY 环境变量传递给服务器
                "OUTPUT_IMAGE_PATH": "OUTPUT_IMAGE_PATH" // 将 OUTPUT_IMAGE_PATH 环境变量传递给服务器
            }
        }
    }
}

注意：

请将 '/absolute/path/to/gemini-image-generator' 替换为您实际的 'gemini-image-generator' 仓库的绝对路径。
如果您在安装步骤中使用的是 'venv' 而不是 'uv'，请将 '"command": "uv"' 改为 '"command": "python"'。
'server name' ("gemini-image-generator") 可以自定义，这将是您在 MCP 客户端中引用此服务器的名称。

基本使用方法

完成安装和配置后，您就可以在 MCP 客户端中指示 AI 助手使用图像生成和变换功能了。

生成新图像：

您可以向 AI 助手发送类似以下的指令：

"Generate an image of a sunset over mountains" (生成山脉日落的图像)
"Create an illustration of a futuristic cityscape" (创建一个未来城市的插画)
"Make a picture of a cat wearing sunglasses" (制作一张猫戴太阳镜的图片)

变换现有图像：

您可以指示 AI 助手变换已有的图像，例如：

"Transform this image by adding snow to the scene" (变换这张图像，在场景中添加雪)
"Edit this photo to make it look like it was taken at night" (编辑这张照片，让它看起来像是在晚上拍摄的)
"Add a dragon flying in the background of this picture" (在这张图片的背景中添加一条飞龙)

对于图像变换功能，您需要提供图像数据。具体取决于 MCP 客户端的支持方式，您可能需要：

上传 Base64 编码的图像数据: 将图像转换为 Base64 编码，并粘贴到客户端中。
提供本地文件路径: 如果客户端支持，您可以提供服务器可以访问的图像文件路径。

生成的或变换后的图像将保存在您配置的输出路径中，并可能在 MCP 客户端中显示（取决于客户端的功能）。

测试 (可选)

您可以使用 'fastmcp' 开发服务器进行测试，无需 MCP 客户端。

fastmcp dev server.py

然后访问 'http://localhost:5173/' 打开 MCP Inspector，您可以直接在网页上测试图像生成工具。

关键词