Image Gen MCP服务器

为AI聊天机器人提供通用图像生成功能

传统的人工智能聊天机器人界面仅限于文本交互，无论其底层语言模型有多强大。Image Gen MCP服务器通过启用以下功能弥合了这一差距 任何LLM驱动的聊天机器人客户端 通过标准化的模型上下文协议（MCP）生成专业质量的图像。

无论您使用的是Claude Desktop、自定义ChatGPT接口、基于Llama的应用程序，还是支持MCP的任何其他LLM客户端，此服务器都使访问民主化 多种AI图像生成模型 包括OpenAI的gpt-image 2、gpt-image 1.5、gpt-image1、dall-e-3、dall-e2和谷歌的Imagen系列（Imagen-4、Imagen-4-ultra、Imagen-4fast、Imagen-3），将纯文本对话转化为丰富的视觉体验。

📦 包管理器：此项目使用紫外线用于快速、可靠的Python包管理。与传统的pip/venv工作流相比，UV提供了更好的依赖解析、更快的安装和适当的环境隔离。

为何这很重要

人工智能生态系统已经发展到包括来自多个提供商（OpenAI、Anthropic、Meta、Google等）的强大语言模型，但图像生成功能仍然是分散的，并且是特定于平台的。这造成了一个巨大的差距：

🚫 有限访问：只有某些平台提供内置图像生成
🔒 供应商锁定：与特定LLM提供商相关的图像功能
⚡ 整合性差：在文本和图像工具之间切换会中断工作流程
🛠️ 复杂设置：每个客户都需要自定义集成

Image Gen MCP服务器通过提供以下功能解决了这个问题：

🌐 通用兼容性：适用于任何启用MCP的LLM客户端
🔄 无缝集成：无上下文切换或工作流中断
⚡ 标准化协议：一台服务器，多个客户端支持
🎨 多提供商支持：访问OpenAI和谷歌最新的图像生成模型
🔧 统一接口：用于多个人工智能提供商的单个API，具有自动模型发现功能

视觉展示

实际使用情况

Claude Desktop with Image Gen MCP *Claude Desktop通过MCP集成无缝生成图像*

生成的示例

*通过MCP服务器生成的高质量图像，展示专业级输出*

用例和应用

🎯 内容创建工作流

博客和作家：直接在书写工具中生成自定义插图
社交媒体经理：在不离开聊天界面的情况下创建特定于平台的图形
营销团队：头脑风暴会议期间视觉概念的快速原型制作
教育工作者：按需生成教材和视觉教具

🚀 开发与设计

UI/UX设计师：在设计讨论期间快速生成模型
前端开发人员：开发环境中的占位符和概念图像
技术作家：用于文档的自定义图表和插图
产品经理：任何LLM驱动工具中的视觉概念交流

🏢 企业集成

客户支持：生成视觉解释和指南
销售团队：根据客户需求定制演示材料
培训计划：在对话界面中创建的视觉学习材料
内部工具：将图像生成添加到现有的LLM驱动的应用程序中

🎨 创意产业

游戏开发者：概念艺术和资产构思
电影与媒体：故事板和概念可视化
建筑：快速视觉参考和情绪板
广告：活动概念开发
艺术家与插画家：具有清晰结构信息和施工指南的图纸参考
艺术生：手势、轮廓、价值和形式研究的练习材料

主要优势：与特定于平台的解决方案不同，这种通用方法意味着您的图像生成功能可以在不同的工具和工作流程中与您一起移动，消除供应商锁定，最大限度地提高工作流程效率。

特性

🎨 多提供商图像生成

多种AI模型：支持OpenAI（gpt-image 2、gpt-image 1.5、gpt-image1、dall-e-3、dall-e-2）和谷歌Gemini（imagen-4、imagen-4-ultra、imagen-4fast、imagen-3）
文本到图像：从文本描述生成高质量图像
图像编辑：使用文本指令编辑现有图像（OpenAI模型）
多种格式：支持PNG、JPEG和WebP输出格式
质量控制：自动、高、中、低质量设置
背景控制：透明、不透明或自动背景选项
动态模型发现：在运行时查询可用的模型和功能

🔗 MCP集成

FastMCP框架：使用最新的MCP Python SDK构建
多个传输：STDIO、HTTP和SSE传输支持
结构化输出：使用适当的模式验证工具响应
资源访问：用于图像检索和管理的MCP资源
提示模板：10多个常见用例的内置模板

💾 存储和缓存

本地存储：具有元数据的有序目录结构
基于URL的访问：为图像生成支持传输的URL
双重访问：即时base64数据+持久资源URI
智能缓存：支持TTL和Redis的基于内存的缓存
自动清理：可配置的文件保留策略

🚀 生产部署

Docker支持：生产就绪的Docker容器
多运输：STDIO用于Claude Desktop，HTTP用于web部署
反向代理：带速率限制的Nginx配置
监控Grafana与普罗米修斯的整合
SSL/TLS：使用Certbot进行自动证书管理

🛠️ 发展特征

类型安全：Pydantic模型的完整类型提示
错误处理：全面的错误处理和记录
配置：基于环境的配置管理
测试：基于Pytest的测试套件，支持异步
开发工具：热重载、Redis Commander、调试日志

快速开始

先决条件

Python 3.10+
UV包管理器
OpenAI API密钥（适用于OpenAI模型）
具有Vertex AI访问权限的Google Cloud服务帐户（适用于Imagen型号，可选）

安装

克隆和设置:

   git clone 
   cd image-gen-mcp
   uv sync

> 备注：此项目使用紫外线用于快速、可靠的Python包管理。与pip相比，UV提供了更好的依赖解析和更快的安装。

配置环境:

   cp .env.example .env
   # Edit .env and add your credentials:
   # - PROVIDERS__OPENAI__API_KEY for OpenAI models
   # - PROVIDERS__GEMINI__API_KEY for Imagen models (path to service account JSON file)

对于Imagen模型（顶点AI设置）:

1. 首选谷歌云控制台 1. 为您的项目启用Vertex AI API 1. 创建具有“顶点AI用户”角色的服务帐户 1. 将JSON密钥文件下载到项目目录 1. 集 PROVIDERS__GEMINI__API_KEY 到JSON文件的路径

测试设置:

   uv run python scripts/dev.py setup
   uv run python scripts/dev.py test

运行服务器

发展模式

# HTTP transport for web development and testing
./run.sh dev

# HTTP transport with development tools (Redis Commander)
./run.sh dev --tools

# STDIO transport for Claude Desktop integration  
./run.sh stdio

# Production deployment with monitoring
./run.sh prod

# Stop all services
./run.sh stop

手动执行

# STDIO transport (default) - for Claude Desktop
uv run python -m image_gen_mcp.server

# HTTP transport - for web deployment
uv run python -m image_gen_mcp.server --transport streamable-http --port 3001

# SSE transport - for real-time applications
uv run python -m image_gen_mcp.server --transport sse --port 8080

# With custom configuration
uv run python -m image_gen_mcp.server --config /path/to/.env --log-level DEBUG

# Enable CORS for web development
uv run python -m image_gen_mcp.server --transport streamable-http --cors

命令行选项

uv run python -m image_gen_mcp.server --help

Image Gen MCP Server - Generate and edit images using OpenAI's gpt-image models and Google's Imagen series

options:
  --config PATH         Path to configuration file (.env format)
  --log-level LEVEL     Set logging level (DEBUG, INFO, WARNING, ERROR, CRITICAL)
  --transport TYPE      Transport method (stdio, sse, streamable-http)
  --port PORT          Port for HTTP transports (default: 3001)
  --host HOST          Host address for HTTP transports (default: 127.0.0.1)
  --cors               Enable CORS for web deployments
  --version            Show version information
  --help               Show help message

Examples:
  # Claude Desktop integration
  uv run python -m image_gen_mcp.server

  # Web deployment with Redis cache
  uv run python -m image_gen_mcp.server --transport streamable-http --port 3001

  # Development with debug logging and tools
  uv run python -m image_gen_mcp.server --log-level DEBUG --cors

MCP客户端集成

此服务器与 任何兼容MCP的聊天机器人客户端以下是配置示例：

克劳德桌面（拟人）

{
  "mcpServers": {
    "image-gen-mcp": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/image-gen-mcp",
        "run",
        "image-gen-mcp"
      ],
      "env": {
        "PROVIDERS__OPENAI__API_KEY": "your-api-key-here"
      }
    }
  }
}

克劳德代码（Anthropic CLI）

# First, create the startup script (one-time setup)
# This is already included in the repository as start-mcp.sh

# Add MCP server with API key
claude mcp add image-gen-mcp /path/to/image-gen-mcp/start-mcp.sh -e PROVIDERS__OPENAI__API_KEY=your-api-key-here

# Or add without API key if it's in your .env file
claude mcp add image-gen-mcp /path/to/image-gen-mcp/start-mcp.sh

# Verify setup
claude mcp list

Continue.dev（VS代码扩展）

{
  "mcpServers": {
    "image-gen-mcp": {
      "command": "uv",
      "args": ["--directory", "/path/to/image-gen-mcp", "run", "image-gen-mcp"],
      "env": {
        "PROVIDERS__OPENAI__API_KEY": "your-api-key-here"
      }
    }
  }
}

自定义MCP客户端

对于其他MCP兼容应用程序，请使用标准MCP STDIO传输：

uv run python -m image_gen_mcp.server

通用兼容性：此服务器遵循标准MCP协议，确保与整个AI生态系统中当前和未来启用MCP的客户端兼容。

用法示例

基本图像生成

# Use via MCP client
result = await session.call_tool(
    "generate_image",
    arguments={
        "prompt": "A beautiful sunset over mountains, digital art style",
        "quality": "high",
        "size": "1536x1024",
        "style": "vivid"
    }
)

使用提示模板

# Get optimized prompt for social media
prompt_result = await session.get_prompt(
    "social_media_prompt",
    arguments={
        "platform": "instagram",
        "content_type": "product announcement",
        "brand_style": "modern minimalist"
    }
)

访问生成的图像

# Access via resource URI
image_data = await session.read_resource("generated-images://img_20250630143022_abc123")

# Check recent images
history = await session.read_resource("image-history://recent?limit=5")

# Storage statistics
stats = await session.read_resource("storage-stats://overview")

可用工具

`list_available_models`

列出所有可用的图像生成模型及其功能。

退货：包含模型信息、功能和提供者详细信息的词典。

`generate_image`

使用任何支持的模型从文本描述生成图像。

参数:

prompt （必填）：所需图像的文字描述
model （可选）：要使用的模型（例如，“gpt-image 2”、“gpt-image1.5”、“dall-e-3”、“imagen-4”）
quality：“自动”|“高”|“中”|“低”（默认值：“自动）
size：“自动”，预设为“1024x1024”/“1536x1024”或“1024x1536”/“3840x2160”，或（用于 gpt-image-2)任何 WxH 在模型的约束范围内（默认值：“1536x1024”）。接受的值取决于模型。
style：“生动”|“自然”（默认：“生动的”）
output_format：“png”|“jpeg”|“webp”（默认值：“png）
background：“自动”|“透明”|“不透明”（默认值：“自动）

备注：参数可用性取决于所选型号。使用 list_available_models 检查能力。

`edit_image`

使用文本说明编辑现有图像。

参数:

image_data （必填）：Base64编码的图像或数据URL
prompt （必填）：编辑说明
mask_data：用于目标编辑的可选掩码
size, quality, output_format：与generate_image相同

可用资源

generated-images://{image_id} -访问特定生成的图像
image-history://recent -浏览最近一代历史记录
storage-stats://overview -存储使用情况和统计数据
model-info://gpt-image-2 -模型功能和定价（也可用于gpt-image 1.5、gpt-image 1、dall-e-3、dall-e-2）

提示模板

常见用例的内置模板：

创意形象：艺术图像生成
产品摄影：商业产品图片
社交媒体图形：平台优化帖子
博客标题：文章标题图片
OG图像：社交媒体预览图片
英雄横幅：网站英雄部分
电子邮件标题：通讯标题
视频缩略图：YouTube/视频缩略图
信息图：数据可视化图像
艺术风格：特定的艺术运动风格
图纸参考：铅笔绘画实践的结构参考
动态素描：动作和手势捕捉研究
基本形状研究：几何形状构造练习
轮廓图：边缘和形状观察练习
价值研究：光影渲染练习

配置

通过环境变量进行配置或 .env 文件：

# =============================================================================
# Provider Configuration
# =============================================================================
# OpenAI Provider (default enabled)
PROVIDERS__OPENAI__API_KEY=sk-your-openai-api-key-here
PROVIDERS__OPENAI__BASE_URL=https://api.openai.com/v1
PROVIDERS__OPENAI__ORGANIZATION=org-your-org-id
PROVIDERS__OPENAI__TIMEOUT=300.0
PROVIDERS__OPENAI__MAX_RETRIES=3
PROVIDERS__OPENAI__ENABLED=true

# Gemini Provider (requires Vertex AI setup)
# For Imagen models, use path to Google Cloud service account JSON file
PROVIDERS__GEMINI__API_KEY=/path/to/your/vertex-ai-key.json
PROVIDERS__GEMINI__BASE_URL=https://us-central1-aiplatform.googleapis.com/v1
PROVIDERS__GEMINI__TIMEOUT=300.0
PROVIDERS__GEMINI__MAX_RETRIES=3
PROVIDERS__GEMINI__ENABLED=false
PROVIDERS__GEMINI__DEFAULT_MODEL=imagen-4

# =============================================================================
# Image Generation Settings
# =============================================================================
IMAGES__DEFAULT_MODEL=gpt-image-2
IMAGES__DEFAULT_QUALITY=auto
IMAGES__DEFAULT_SIZE=1536x1024
IMAGES__DEFAULT_STYLE=vivid
IMAGES__DEFAULT_MODERATION=auto
IMAGES__DEFAULT_OUTPUT_FORMAT=png
# Base URL for image hosting (e.g., https://cdn.example.com for nginx/CDN)
IMAGES__BASE_HOST=

# =============================================================================
# Server Configuration
# =============================================================================
SERVER__NAME=Image Gen MCP Server
SERVER__VERSION=0.1.0
SERVER__PORT=3001
SERVER__HOST=127.0.0.1
SERVER__LOG_LEVEL=INFO
SERVER__RATE_LIMIT_RPM=50

# =============================================================================
# Storage Configuration
# =============================================================================
STORAGE__BASE_PATH=./storage
STORAGE__RETENTION_DAYS=30
STORAGE__MAX_SIZE_GB=10.0
STORAGE__CLEANUP_INTERVAL_HOURS=24

# =============================================================================
# Cache Configuration
# =============================================================================
CACHE__ENABLED=true
CACHE__TTL_HOURS=24
CACHE__BACKEND=memory
CACHE__MAX_SIZE_MB=500
# CACHE__REDIS_URL=redis://localhost:6379

部署

生产部署

服务器支持Docker、监控和反向代理的生产部署：

# Quick production deployment
./run.sh prod

# Manual Docker Compose deployment
docker-compose -f docker-compose.prod.yml up -d

生产堆栈包括：

Image Gen MCP服务器：主应用程序容器
瑞迪斯：缓存和会话存储
Nginx：具有速率限制的反向代理（单独配置）
普罗米修斯：指标收集
格拉法纳：监控仪表板

接入点：

主要服务： http://localhost:3001 （代理后面）
Grafana仪表板： http://localhost:3000
普罗米修斯： http://localhost:9090 （仅限本地主机）

VPS部署

对于使用SSL、监控和生产强化的VPS部署：

# Download deployment script
wget https://raw.githubusercontent.com/your-repo/image-gen-mcp/main/deploy/vps-setup.sh
chmod +x vps-setup.sh
./vps-setup.sh

功能包括：

Docker容器化
带SSL的Nginx反向代理
自动证书管理（Certbot）
系统监控和记录
防火墙配置
自动备份

看 VPS部署指南详细说明。

Docker配置

可用的Docker Compose配置文件：

# Development with HTTP transport
docker-compose -f docker-compose.dev.yml up

# Development with Redis Commander
docker-compose -f docker-compose.dev.yml --profile tools up

# STDIO transport for desktop integration
docker-compose -f docker-compose.dev.yml --profile stdio up

# Production with monitoring
docker-compose -f docker-compose.prod.yml up -d

发展

开发工具

# Setup development environment
uv run python scripts/dev.py setup

# Run tests
uv run python scripts/dev.py test

# Code quality and formatting
uv run python scripts/dev.py lint     # Check code quality with ruff and mypy
uv run python scripts/dev.py format   # Format code with black

# Run example client
uv run python scripts/dev.py example

# Development server with auto-reload
./run.sh dev --tools           # Includes Redis Commander UI

测试

# Run full test suite
./run.sh test

# Run specific test categories
uv run pytest tests/unit/      # Unit tests only
uv run pytest tests/integration/ # Integration tests only
uv run pytest -v --cov=image_gen_mcp # With coverage

建筑

服务器遵循模块化、生产就绪的架构：

核心组件：

服务器层 (server.py)：基于FastMCP的MCP服务器，支持多传输
配置 (config/)：基于环境的设置管理和验证
工具层 (tools/)：图像生成和编辑功能
资源层 (resources/)：用于数据访问和模型注册表的MCP资源
存储管理器 (storage/)：组织本地图像存储并进行清理
缓存管理器 (utils/cache.py)：基于内存和Redis的缓存系统

多提供商架构：

提供商注册表 (providers/registry.py)：集中式提供商和模型管理
供应商基础 (providers/base.py)：所有提供程序的抽象基类
OpenAI提供商 (providers/openai.py)：OpenAI API与重试逻辑集成
Gemini供应商 (providers/gemini.py)：Google Gemini API集成
类型系统 (types/)：用于类型安全的Pydantic模型
验证 (utils/validators.py)：输入验证和净化

基础设施：

提示模板 (prompts/)：优化提示的模板系统
动态模型发现：运行时模型能力检测
参数翻译：提供程序之间的自动参数映射

部署：

Docker支持：开发和生产容器
多运输：STDIO、HTTP、SSE传输层
监控：普罗米修斯指标和Grafana仪表板
反向代理：带SSL和速率限制的Nginx配置

成本估算

服务器为操作提供成本估算：

文本输入：每100万代币约5美元
图像输出：每100万代币约40美元（每张图片约1750个代币）
典型成本：每张图像生成约0.07美元

错误处理

全面的错误处理包括：

API速率限制和重试次数
参数验证无效
存储错误恢复
缓存故障回退
详细的错误记录

安全

安全功能包括：

OpenAI API密钥保护
输入验证和净化
文件系统访问控制
速率限制保护
日志中没有凭据暴露

许可证

MIT许可证-有关详细信息，请参阅许可证文件。

贡献

分叉存储库
创建要素分支
进行更改
添加新功能的测试
运行测试套件
提交拉取请求

支持

对于问题和疑问：

检查故障排除指南
审查常见问题
在GitHub上打开一个问题

______________________________________________________________________

内置于❤️ 使用模型上下文协议和OpenAI的gpt-image 2

人工智能集成的未来

模型上下文协议代表了向 标准化人工智能工具集成随着越来越多的LLM客户端采用MCP支持，像这样的服务器通过在整个生态系统中提供通用功能变得越来越有价值。

当前MCP采用情况：

✅ 克劳德桌面 （Anthropic）-完全支持MCP
✅ Continue.dev -VS代码扩展与MCP集成
✅ Zed编辑 -内置MCP支持编码工作流程
🚀 成长中的生态系统 -新客户定期采用MCP

视觉：人工智能能力的未来 模块化、可互操作、用户控制 而不是锁定到特定平台。