Gemini Image Generation MCP

Gemini 图像与视频生成 MCP

一个可用于生产环境的模型上下文协议（MCP）服务，可让 Claude 和其他大模型使用 Google 的 Gemini AI 模型（Gemini 2.0 Flash 和 Veo 2.0）生成图像和视频。

🌟 功能

核心能力

• ✨ 图像生成 - 使用 Gemini 2.0 Flash（gemini-2.0-flash-preview-image-generation）创建图像
• 🎬 视频生成 - 使用 Veo 2.0（veo-2.0-generate-001）生成视频
• 🎨 图像转视频 - 使用 Veo 2.0 将图像制作成动画视频
• 💾 本地存储 - 自动保存生成的内容
• ⚙️ 参数控制 - 微调 temperature、topK 和 topP

生产环境功能

• 🔒 可选身份验证 - 基于令牌的 API 安全机制
• ⚡ 响应缓存 - 为重复的提示词提供 30 分钟 TTL 缓存
• 📊 速率限制 - 防止 API 滥用（常规请求 100 次/15 分钟，生成请求 20 次/15 分钟）
• ✅ 输入验证 - 全面的请求验证
• 📄 分页 - 支持排序的高效图库浏览
• 🔐 可配置的 CORS - 基于环境变量控制来源
• 📚 OpenAPI 文档 - 在 /api-docs 提供交互式 Swagger UI
• 🧪 测试套件 - 使用 Jest 编写的 17 项自动化测试
• 🐳 Docker 支持 - 轻松进行容器化部署

📋 前置条件

• Node.js 18 或更高版本
• Google API 密钥，并拥有以下模型的访问权限：
  • Gemini 2.0 Flash（图像生成）
  • Veo 2.0（视频生成）
• Docker（可选，用于容器化部署）

🚀 快速开始

安装

# Clone the repository
git clone https://github.com/your-org/gemini-image-gen-mcp.git
cd gemini-image-gen-mcp

# Install dependencies
npm install

# Configure environment
cp .env.example .env
# Edit .env and add your GEMINI_API_KEY

运行服务

选项 1：Node.js（开发）

# MCP server only (for Claude integration)
npm start

# Web server with REST API + UI
npm run web

# Or use the start script
./start-server.sh --both      # Both servers
./start-server.sh --mcp-only  # MCP only
./start-server.sh --web-only  # Web only

选项 2：Docker（生产环境）

docker-compose up -d

Web 界面将在 http://localhost:3070 上提供。

🎯 API 端点

生成端点

• POST /api/generate-image - 根据文本提示词生成图像
• POST /api/generate-video - 根据文本提示词生成视频
• POST /api/generate-video-from-image - 根据初始图像生成视频

图库端点

• GET /api/images?page=1&limit=20 - 列出生成的图像（分页）
• GET /api/videos?page=1&limit=20 - 列出生成的视频（分页）

系统端点

• GET /health - 健康检查
• GET /api-docs - 交互式 Swagger UI 文档
• GET /api-docs.json - OpenAPI JSON 规范
• GET /api/cache/stats - 查看缓存统计信息
• POST /api/cache/clear - 清除响应缓存（需要身份验证）

📖 API 文档

交互式 API 文档地址：

• Swagger UI：http://localhost:3070/api-docs
• OpenAPI JSON：http://localhost:3070/api-docs.json

Swagger UI 提供：

• 完整的端点文档
• 请求/响应架构
• 即时试用功能
• 身份验证测试
• 参数说明和示例

🔐 身份验证

身份验证为可选，可通过设置 API_AUTH_TOKEN 环境变量启用：

# In .env file
API_AUTH_TOKEN=your-secure-token-here

使用身份验证

Bearer 令牌（推荐）：

curl -H "Authorization: Bearer your-secure-token-here" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "A sunset over mountains"}' \
  http://localhost:3070/api/generate-image

查询参数（备选）：

curl -X POST \
  "http://localhost:3070/api/generate-image?token=your-secure-token-here" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "A sunset over mountains"}'

⚙️ 配置选项

所有配置均通过 .env 中的环境变量完成：

变量	说明	默认值
GEMINI_API_KEY	必需 - Google Gemini API 密钥	-
API_AUTH_TOKEN	可选 - API 身份验证令牌	-
MCP_AUTH_TOKEN	可选 - MCP 服务身份验证	-
PORT	Web 服务端口	3070
OUTPUT_DIR	生成文件的基础目录	./generated-images
LOG_LEVEL	日志级别（debug、info、warn、error）	info
CORS_ORIGINS	允许的来源，以逗号分隔	*
RATE_LIMIT_MAX	每个 IP 每 15 分钟的最大请求数	100
GENERATION_RATE_LIMIT	每 15 分钟的最大生成请求数	20
ENABLE_CACHE	启用响应缓存	true

🧪 测试

# Run all tests
npm test

# Run tests in watch mode
npm run test:watch

# Run tests with coverage report
npm run test:coverage

当前测试覆盖范围：

• 2 个测试套件
• 17 项测试通过
• 覆盖范围：身份验证、工具架构、输入验证

🐳 Docker 部署

使用 Docker Compose（推荐）

# Start services
docker-compose up -d

# View logs
docker-compose logs -f

# Stop services
docker-compose down

手动构建 Docker

# Build image
docker build -t gemini-image-gen-mcp .

# Run container
docker run -d \
  -p 3070:3070 \
  -e GEMINI_API_KEY=your_key_here \
  -v $(pwd)/generated-images:/app/generated-images \
  -v $(pwd)/generated-videos:/app/generated-videos \
  gemini-image-gen-mcp

🔌 与 Claude 搭配使用

Claude Desktop 配置

将以下内容添加到 Claude Desktop 配置文件中：

macOS： ~/Library/Application Support/Claude/claude_desktop_config.json Windows： %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "gemini-image-generation": {
      "command": "node",
      "args": ["/full/path/to/gemini-image-gen-mcp/src/mcp-server.js"],
      "env": {
        "GEMINI_API_KEY": "your-gemini-api-key-here"
      }
    }
  }
}

Claude API 使用方法

# Example prompt to Claude
"Please generate an image of a serene mountain landscape at sunset using the Gemini image generation tool"

Claude 将自动调用 MCP 服务的 generate_image 工具。

🎨 Web 界面

Web 界面包含三个主要部分：

1. 生成器选项卡

• 输入用于生成图像/视频的文本提示词
• 调整生成参数（temperature、topP、topK）
• 使用示例提示词进行快速测试
• 查看包含增强提示词的生成结果

2. 图库选项卡

• 浏览所有生成的图像和视频
• 支持分页（每页 20 项）
• 按最新内容排序
• 点击即可查看完整尺寸

3. 关于选项卡

• 项目信息
• 功能列表
• 配置详情
• API 文档链接

📊 性能与优化

响应缓存

• 自动缓存成功的生成结果
• 30 分钟 TTL（可配置）
• 减少重复提示词带来的 API 成本
• 缓存键包含：提示词 + 模型 + 参数
• 在 /api/cache/stats 查看缓存统计信息

指数退避

• 智能视频轮询（2 秒 → 最长 30 秒）
• 将 API 调用减少约 60%
• 防止触发 API 速率限制

异步 I/O

• 非阻塞文件操作
• 提升服务响应能力
• 更好地处理并发请求

分页

• 内存使用量恒定
• 可处理包含数千项的图库
• 按修改时间排序

🛡️ 安全功能

• ✅ 输入验证 - 使用 express-validator 验证所有参数
• ✅ 速率限制 - 两级系统（通用 + 生成专用）
• ✅ 请求大小限制 - 最大 10MB，防止 DoS
• ✅ CORS 配置 - 基于环境变量控制来源
• ✅ 可选身份验证 - 基于令牌的 API 安全机制
• ✅ 不硬编码密钥 - 所有凭据均通过环境变量提供

🔧 故障排除

常见问题

“GEMINI_API_KEY 未设置”错误：

# Make sure .env file exists and contains:
GEMINI_API_KEY=your_actual_key_here

端口已被占用：

# Change port in .env file:
PORT=3080

缓存无法正常工作：

# Check cache is enabled in .env:
ENABLE_CACHE=true
# View cache stats:
curl http://localhost:3070/api/cache/stats

超出速率限制：

# Increase limits in .env:
RATE_LIMIT_MAX=200
GENERATION_RATE_LIMIT=50

📝 API 请求示例

生成图像

curl -X POST http://localhost:3070/api/generate-image \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "A futuristic cityscape at night with neon lights",
    "temperature": 0.8,
    "topP": 0.95,
    "topK": 40
  }'

生成视频

curl -X POST http://localhost:3070/api/generate-video \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "A bird flying through a forest",
    "temperature": 1.0
  }'

分页列出图像

curl "http://localhost:3070/api/images?page=1&limit=10"

🤝 贡献

欢迎贡献！请按以下步骤操作：

1. Fork 此代码仓库
2. 创建功能分支（git checkout -b feature/amazing-feature）
3. 提交更改（git commit -m 'Add amazing feature'）
4. 推送到分支（git push origin feature/amazing-feature）
5. 发起 Pull Request

开发指南

• 提交前运行测试：npm test
• 遵循现有代码风格
• 为新功能更新文档
• 为新功能添加测试

📄 许可证

ISC

🙏 致谢

• 基于 Model Context Protocol 构建
• 由 Google Gemini AI 提供支持
• 使用 Veo 2.0 生成视频

📞 支持

如有问题或疑问：

• 在 GitHub 上提交 issue
• 查看 API 文档
• 查阅上方的故障排除部分

---

为 AI 社区倾心打造 ❤️