图像生成服务器

🎨 图像服务器

高品质 模型上下文协议（MCP） 该服务器使人工智能助手能够使用谷歌的Gemini和Imagen模型生成图像。

📖 概述

MCP图像 为任何兼容MCP的客户端（如Claude Desktop、带有GitHub Copilot的VS Code或自定义应用程序）提供AI驱动的图像生成功能。它连接到谷歌的人工智能平台，提供对尖端图像生成模型的访问。

为什么使用此MCP服务器？

• 🔄 动态模型选择：查询可用型号，并根据您的需求选择最佳型号
• 🖼️ 高质量输出：访问Gemini和Imagen型号，获取2K/4K分辨率的图像
• 📐 灵活的纵横比：支持多种宽高比（1:1、16:9、9:16等）
• 🔤 文本渲染：Gemini模型图像渲染中的强文本
• �� 安全配置：通过环境变量安全存储API密钥
• 🚀 易于集成：可与任何兼容MCP的AI助手配合使用
• 📦 最小依赖性：只需要 fastmcp -所有其他功能都使用Python标准库

✨ 特性

🔧 先决条件

• Python 3.9+ （使用3.9+中提供的标准库功能）
• 谷歌人工智能API密钥 (在这里买一个)
• 枕头 （通过自动安装 requirements.txt 用于调整大小/优化）
• 枕头 （通过安装 requirements.txt HEIC/HAIF支持）
• MCP兼容客户端（Claude Desktop、VS Code with Copilot等）

🚀 快速开始

1.克隆存储库

git clone https://github.com/vipincr/imagen-mcp.git
cd imagen-mcp

2.安装依赖项

pip install -r requirements.txt

或者使用虚拟环境（推荐）：

python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
pip install -r requirements.txt

3.配置API密钥

创建一个 .env 项目根目录中的文件：

GOOGLE_AI_API_KEY=your_google_ai_api_key_here

或者直接在MCP客户端配置中将其设置为环境变量。

💡 小贴士：从获取API密钥 谷歌AI工作室

4.测试服务器

python run_server.py

⚙️ 配置

环境变量

模型选择回退（最高优先级优先）： 显式工具参数➜ 运行时 set_image_model ➜ IMAGEN_MODEL_ID 环境变量➜ 内置默认值 gemini-3-pro-image.

支持的纵横比

备注：并非所有型号都支持所有纵横比。如果不支持，服务器将自动重试，不考虑纵横比。

🔌 MCP客户端集成

服务器通过stdio与MCP通信，因此任何MCP客户端都可以 按需生成 — 你永远不会自己运行服务器进程。建议的启动命令是 自举发射器 run_mcp.py：第一次成为客户 启动它，它会在以下位置创建一个私有virtualenv ~/.imagen-mcp/venv，安装此 打包并启动服务器（每次后续启动约0.4秒）。你需要的全部 在机器上 Python 3 以及第一次运行的网络访问。

实时配置示例 examples/.

Claude 代码

一个命令 （用户范围——每个项目都有）：

export GOOGLE_AI_API_KEY=your_key_here
./scripts/add-to-claude-code.sh

这运行 claude mcp add imagen --scope user … -- python3 <repo>/run_mcp.py. 然后，Claude Code在第一次需要时自动启动服务器 图像工具。证实 claude mcp list.

每个项目 改为：复制 examples/claude_code.mcp.json 到您的项目根目录 .mcp.json （上面写着 ${GOOGLE_AI_API_KEY} 从你的 环境，因此文件中没有存储密钥）。

Claude 桌面版

合并 examples/claude_desktop_config.json 在配置文件中，使用签出的绝对路径和真实密钥：

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

{
  "mcpServers": {
    "imagen": {
      "command": "python3",
      "args": ["/absolute/path/to/imagen-mcp/run_mcp.py"],
      "env": {
        "GOOGLE_AI_API_KEY": "your_api_key_here"
      }
    }
  }
}

重新启动克劳德桌面；这个 图像 工具出现在MCP工具菜单下。

VS代码与GitHub Copilot

安装捆绑的扩展（请参阅 VS代码扩展) — 它全局注册服务器并为您管理API密钥，因此不需要手动 配置是必需的。要用手将其连接起来，请添加 .vscode/mcp.json:

{
  "servers": {
    "imagen": {
      "command": "python3",
      "args": ["/absolute/path/to/imagen-mcp/run_mcp.py"],
      "env": {
        "GOOGLE_AI_API_KEY": "your_api_key_here"
      }
    }
  }
}

使用紫外线

如果你有 紫外线 安装后，您可以跳过 引导启动器并让uv管理环境：

{
  "mcpServers": {
    "imagen": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/imagen-mcp", "imagen-mcp"],
      "env": {
        "GOOGLE_AI_API_KEY": "your_api_key_here"
      }
    }
  }
}

API密钥解析

服务器按以下顺序查找密钥： GOOGLE_AI_API_KEY 环境 变量（上面设置的配置）➜ OS钥匙链（通过 keyring) ➜ a .env repo根目录中的文件。以适合客户的方式提供；这个 MCP配置中的env-var是最简单、最可移植的。

📚 工具参考

check_api_status

请验证您的API密钥是否已配置并有效。

参数： 无

退货：

{
  "success": true,
  "api_key_configured": true,
  "api_key_valid": true,
  "total_models": 25,
  "image_models": 3,
  "current_model": "gemini-3-pro-image"
}

list_image_models

发现API密钥的可用图像生成模型。

参数： 无

退货：

{
  "success": true,
  "models": [
    {
      "name": "gemini-3-pro-image",
      "display_name": "Gemini 3 Pro (Image Preview)",
      "description": "Fast image generation model..."
    }
  ],
  "current_model": null,
  "count": 3
}

set_image_model

选择要用于图像生成的模型。

参数：

退货：

{
  "success": true,
  "model": "gemini-3-pro-image",
  "message": "Model set to 'gemini-3-pro-image'. Ready for image generation."
}

generate_image_from_prompt

根据文本描述生成图像。

参数：

退货：

{
  "success": true,
  "image_base64": "iVBORw0KGgo...",
  "mime_type": "image/png",
  "extension": ".png",
  "size_bytes": 1234567,
  "model_used": "gemini-3-pro-image"
}

generate_image_with_references_from_files

使用生成图像 1-3个参考图像 （磁盘上的文件）加上文本提示。

重要提示： 参考图像是 视觉输入 --您可以指示模型在生成的图像中包含引用的对象/主题（按原样或修改后），而不仅仅是复制其样式。

参数：

generate_image_with_references_resized_from_files

同 generate_image_with_references_from_files，但另外会调整/压缩到目标边界。

generate_and_save_image_with_references

从引用生成并保存到的便利工具 output_path （如果缺少，则添加扩展名）。

generate_and_save_image_with_references_resized

从引用生成、调整大小/压缩并保存到的便利工具 output_path.

save_image_to_file

将base64编码的图像保存到文件中。

参数：

退货：

{
  "success": true,
  "saved_path": "/absolute/path/to/image.png",
  "size_bytes": 1234567
}

generate_and_save_image

一次操作生成图像并将其保存到文件中。

参数：

退货：

{
  "success": true,
  "saved_path": "/absolute/path/to/image.png",
  "mime_type": "image/png",
  "size_bytes": 1234567,
  "model_used": "gemini-3-pro-image"
}

generate_image_resized_from_prompt

生成图像，然后调整其大小/压缩以适应给定的尺寸。

参数：

退货：

{
  "success": true,
  "image_base64": "iVBORw0KGgo...",
  "mime_type": "image/jpeg",
  "extension": ".jpg",
  "size_bytes": 123456,
  "model_used": "gemini-3-pro-image",
  "resized": true,
  "max_width": 1024,
  "max_height": 1024
}

generate_and_save_image_resized

生成图像，调整其大小/压缩，并保存到磁盘（与高分辨率保存路径分开）。

参数：

退货：

{
  "success": true,
  "saved_path": "/absolute/path/to/image.jpg",
  "mime_type": "image/jpeg",
  "size_bytes": 123456,
  "model_used": "gemini-3-pro-image",
  "resized": true,
  "max_width": 1024,
  "max_height": 1024
}

convert_image

将图像转换为另一种格式，可选择为favicons发出多尺寸的ICO。

参数：

退货：

{
  "success": true,
  "saved_path": "/absolute/path/to/favicon.ico",
  "mime_type": "image/x-icon",
  "sizes": [16,32,48,64,128],
  "format": "ico"
}

💡 使用示例

一旦服务器连接到您的AI助手，您就可以使用自然语言：

首次设置

“检查我的API密钥是否配置正确” “列出可用的图像生成模型” “将模型设置为gemini-3.1-flash-image”

基本图像生成

“用鲜艳的橙色和紫色在山上创造日落”

产品摄影

“在具有戏剧性照明的极简主义白色表面上创建智能手表的产品照片”

具体尺寸

“为一个以抽象电路图案为特色的技术博客生成16:9的横幅图像”

保存到项目

“为我的网站生成英雄图像并将其保存到assets/images/hero.png”

🏗️ 项目结构

imagen-mcp/
├── imagen_mcp/              # Main package (renamed from image_generator)
│   ├── __init__.py          # Package initialization & public API
│   ├── core.py              # Core image generation & model listing logic
│   └── server.py            # MCP server implementation with tools
├── run_server.py            # Standalone server entry point
├── pyproject.toml           # Python package configuration
├── requirements.txt         # Python dependencies
├── LICENSE                  # MIT License
├── README.md                # This file
├── CONTRIBUTING.md          # Contribution guidelines
└── vscode-extension/        # VS Code extension to manage MCP config
    ├── package.json
    ├── tsconfig.json
    ├── src/extension.ts     # Extension implementation
    ├── scripts/
    │   ├── copy-server.js   # Copies imagen_mcp to server/ during build
    │   └── bump-version.js  # Version management
    └── server/               # Bundled server code (generated during build)
        ├── imagen_mcp/       # Copied from root during build
        └── run_server.py    # Extension entry point

🧩 VS代码扩展（可选）

您可以通过捆绑的扩展从VS Code内部管理MCP服务器。

构建和安装

面向最终用户（市场安装-自动更新）

• 从VS代码市场安装（搜索“Imagen MCP服务器”）。Marketplace会安装新版本的自动更新。
• 安装后：运行下面的命令来设置API密钥和模型。

用于手动/VIX安装

1. cd vscode-extension
2. npm install
3. npm run package （创建 imagen-mcp-vscode-<version>.vsix)
4. 在VS Code中，运行“扩展：从VSIX安装…”并选择 .vsix （更新需要安装新的VSIX）。

对于贡献者（发布一个版本）

1. 集 publisher 在 vscode-extension/package.json （已经 gramini-consulting).
2. 集 VSCE_PAT （具有Marketplace发布权限的个人访问令牌）。
3. cd vscode-extension && npm install && npm run package && npx vsce publish （根据需要在发布前更新版本）。
4. 在GitHub中标记发布并附加 .vsix 对于非市场安装。

命令（命令选项板→ “图像MCP”）

• 设置API密钥 –验证并存储在VS Code Secret Storage（操作系统密钥链）中一次，在所有工作区共享。
• 清除API密钥 –删除存储的密钥。
• 选择模型 –更新应用程序范围的设置 imagenMcp.modelId （默认值 gemini-3-pro-image).
• 重新安装Python环境 –重建共享虚拟环境。

扩展注册MCP服务器 全球范围内 通过VS Code的MCP提供商API (vscode.lm.registerMcpServerDefinitionProvider，VS代码1.101+）。确实如此 不 写 .vscode/mcp.json 进入你的工作空间；API密钥被注入到 启动时从Secret Storage访问服务器进程。

扩展设置

• imagenMcp.modelId （应用范围，默认值 gemini-3-pro-image)--默认图像模型，应用于所有工作区。

API密钥是有意的 不 一个设置——它只存在于秘密存储中。

🛡️ 安全考虑

• API密钥保护：永远不要提交API密钥。使用环境变量或 .env 文件
• 安全存储：The .env 文件包含在 .gitignore 默认情况下
• MCP配置：API密钥可以通过MCP客户端env配置安全传递
• 文件系统访问：注意图像的保存位置

🔍 故障排除

常见问题

“缺少API密钥”错误

• 确保 GOOGLE_AI_API_KEY 在您的环境中设置或 .env 文件
• 检查一下 .env 文件位于项目根目录中
• 验证密钥是否在MCP客户端配置中传递

“未选择模型”错误

• 使用 list_image_models 查看可用型号
• 使用 set_image_model 在生成之前选择一个

“纵横比未启用”错误

• 服务器自动重试，没有纵横比
• 某些型号不支持自定义纵横比

未找到图像模型

• 您的API密钥可能无法访问图像生成模型
• 检查您的Google AI Studio帐户以访问API

与MCP客户端的连接问题

• 验证MCP配置中的路径是否为绝对路径
• 检查Python是否在您的系统PATH中
• 确保安装了所有依赖项

调试

检查您的MCP客户端的日志：

• Claude 桌面版：检查应用程序日志
• VS Code：查看输出面板→ MCP

🤝 贡献

我们欢迎捐款！请看 贡献.md 作为指导方针。

贡献方式

• 🐛 报告错误和问题
• 💡 建议新功能
• 📖 改进文档
• 🔧 提交拉取请求

📄 许可证

该项目根据 MIT 许可证 -看看 许可证 文件以获取详细信息。

MIT License

Copyright (c) 2025 Vipin Ravindran

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

🙏 致谢

• 模型上下文协议 -协议规范
• FastMCP -Python MCP框架
• 谷歌双子座 -图像生成模型

📬 支持

• 问题: GitHub Issues
• 讨论: GitHub讨论

Made with ❤️ for the MCP community