金大哥 - gpt-image-mcp MCP 详情

article

README

🚀 图像生成MCP服务器

图像生成MCP服务器旨在为AI聊天机器人赋能，实现通用的图像生成功能。传统的AI聊天机器人界面，无论其底层语言模型多么强大，通常都局限于纯文本交互。而本服务器通过标准化的模型上下文协议（MCP），使任何基于大语言模型（LLM）的聊天机器人客户端都能生成专业品质的图像。

🚀 快速开始

前提条件

Python 3.10及以上版本
UV包管理器
OpenAI API密钥（用于OpenAI模型）
Google Gemini API密钥（用于Gemini模型，可选）

安装步骤

克隆并设置项目：

git clone <repository-url>
cd image-gen-mcp
uv sync

注意：本项目使用UV进行快速、可靠的Python包管理。与传统的pip/venv工作流相比，UV提供了更好的依赖解析、更快的安装速度和更完善的环境隔离。

配置环境：

cp .env.example .env
# 编辑.env文件并添加你的API密钥：
# - PROVIDERS__OPENAI__API_KEY用于OpenAI模型
# - PROVIDERS__GEMINI__API_KEY用于Gemini模型（可选）

测试设置：

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

运行服务器

开发模式

# 用于Web开发和测试的HTTP传输
./run.sh dev

# 带有开发工具（Redis Commander）的HTTP传输
./run.sh dev --tools

# 用于Claude Desktop集成的STDIO传输
./run.sh stdio

# 带有监控的生产部署
./run.sh prod

手动执行

# STDIO传输（默认） - 用于Claude Desktop
uv run python -m gpt_image_mcp.server

# HTTP传输 - 用于Web部署
uv run python -m gpt_image_mcp.server --transport streamable-http --port 3001

# SSE传输 - 用于实时应用程序
uv run python -m gpt_image_mcp.server --transport sse --port 8080

# 自定义配置
uv run python -m gpt_image_mcp.server --config /path/to/.env --log-level DEBUG

# 为Web开发启用CORS
uv run python -m gpt_image_mcp.server --transport streamable-http --cors

命令行选项

uv run python -m gpt_image_mcp.server --help

Image Gen MCP Server - 使用OpenAI的gpt-image-1模型生成和编辑图像

选项:
  --config PATH         配置文件的路径（.env格式）
  --log-level LEVEL     设置日志级别（DEBUG, INFO, WARNING, ERROR, CRITICAL）
  --transport TYPE      传输方法（stdio, sse, streamable-http）
  --port PORT          HTTP传输的端口（默认值: 3001）
  --host HOST          HTTP传输的主机地址（默认值: 127.0.0.1）
  --cors               为Web部署启用CORS
  --version            显示版本信息
  --help               显示帮助信息

示例:
  # Claude Desktop集成
  uv run python -m gpt_image_mcp.server

  # 带有Redis缓存的Web部署
  uv run python -m gpt_image_mcp.server --transport streamable-http --port 3001

  # 带有调试日志和工具的开发模式
  uv run python -m gpt_image_mcp.server --log-level DEBUG --cors

MCP客户端集成

本服务器可与任何支持MCP的聊天机器人客户端配合使用。以下是配置示例：

Claude Desktop（Anthropic）

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

Continue.dev（VS Code扩展）

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

自定义MCP客户端

对于其他支持MCP的应用程序，使用标准的MCP STDIO传输：

uv run python -m gpt_image_mcp.server

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

✨ 主要特性

🎨 多供应商图像生成

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

🔗 MCP集成

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

💾 存储与缓存

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

🚀 生产部署

Docker支持：提供适用于生产环境的Docker容器。
多传输方式：支持用于Claude Desktop的STDIO和用于Web部署的HTTP。
反向代理：使用Nginx进行反向代理，并配置速率限制。
监控：集成Prometheus和Grafana进行监控。
SSL/TLS：使用Certbot自动管理证书。

🛠️ 开发特性

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

📦 安装指南

克隆项目

git clone <repository-url>
cd image-gen-mcp

安装依赖

uv sync

配置环境

cp .env.example .env
# 编辑.env文件并添加API密钥

测试安装

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

💻 使用示例

基础用法

# 通过MCP客户端使用
result = await session.call_tool(
    "generate_image",
    arguments={
        "prompt": "A beautiful sunset over mountains, digital art style",
        "quality": "high",
        "size": "1536x1024",
        "style": "vivid"
    }
)

高级用法

使用提示模板

# 获取针对社交媒体优化的提示
prompt_result = await session.get_prompt(
    "social_media_prompt",
    arguments={
        "platform": "instagram",
        "content_type": "product announcement",
        "brand_style": "modern minimalist"
    }
)

访问生成的图像

# 通过资源URI访问
image_data = await session.read_resource("generated-images://img_20250630143022_abc123")

# 查看最近的图像
history = await session.read_resource("image-history://recent?limit=5")

# 存储统计信息
stats = await session.read_resource("storage-stats://overview")

📚 详细文档

可用工具

`list_available_models`

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

返回值：包含模型信息、功能和供应商详细信息的字典。

`generate_image`

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

参数：

prompt（必需）：所需图像的文本描述。
model（可选）：要使用的模型（例如，"gpt-image-1"、"dall-e-3"、"imagen-4"）。
quality："auto" | "high" | "medium" | "low"（默认值："auto"）。
size："1024x1024" | "1536x1024" | "1024x1536"（默认值："1536x1024"）。
style："vivid" | "natural"（默认值："vivid"）。
output_format："png" | "jpeg" | "webp"（默认值："png"）。
background："auto" | "transparent" | "opaque"（默认值："auto"）。

注意：参数的可用性取决于所选的模型。使用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-1 - 模型功能和定价信息。

提示模板

内置了适用于常见用例的提示模板：

创意图像：用于艺术图像生成。
产品摄影：用于商业产品图像。
社交媒体图形：针对特定平台优化的帖子。
博客标题：文章标题图像。
OG图像：社交媒体预览图像。
英雄横幅：网站英雄部分的图像。
电子邮件标题：时事通讯标题。
视频缩略图：YouTube/视频缩略图。
信息图表：数据可视化图像。
艺术风格：特定艺术运动风格。

配置

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

# =============================================================================
# 供应商配置
# =============================================================================
# OpenAI供应商（默认启用）
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供应商（默认禁用）
PROVIDERS__GEMINI__API_KEY=your-gemini-api-key-here
PROVIDERS__GEMINI__BASE_URL=https://generativelanguage.googleapis.com/v1beta/
PROVIDERS__GEMINI__TIMEOUT=300.0
PROVIDERS__GEMINI__MAX_RETRIES=3
PROVIDERS__GEMINI__ENABLED=false
PROVIDERS__GEMINI__DEFAULT_MODEL=imagen-4

# =============================================================================
# 图像生成设置
# =============================================================================
IMAGES__DEFAULT_MODEL=gpt-image-1
IMAGES__DEFAULT_QUALITY=auto
IMAGES__DEFAULT_SIZE=1536x1024
IMAGES__DEFAULT_STYLE=vivid
IMAGES__DEFAULT_MODERATION=auto
IMAGES__DEFAULT_OUTPUT_FORMAT=png
# 图像托管的基础URL（例如，https://cdn.example.com用于nginx/CDN）
IMAGES__BASE_HOST=

# =============================================================================
# 服务器配置
# =============================================================================
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__BASE_PATH=./storage
STORAGE__RETENTION_DAYS=30
STORAGE__MAX_SIZE_GB=10.0
STORAGE__CLEANUP_INTERVAL_HOURS=24

# =============================================================================
# 缓存配置
# =============================================================================
CACHE__ENABLED=true
CACHE__TTL_HOURS=24
CACHE__BACKEND=memory
CACHE__MAX_SIZE_MB=500
# CACHE__REDIS_URL=redis://localhost:6379

部署

生产部署

服务器支持使用Docker、监控和反向代理进行生产部署：

# 快速生产部署
./run.sh prod

# 手动使用Docker Compose部署
docker-compose -f docker-compose.prod.yml up -d

生产环境栈包括：

图像生成MCP服务器：主应用程序容器。
Redis：用于缓存和会话存储。
Nginx：带有速率限制的反向代理（单独配置）。
Prometheus：指标收集。
Grafana：监控仪表盘。

访问点：

主服务：http://localhost:3001（通过代理）
Grafana仪表盘：http://localhost:3000
Prometheus：http://localhost:9090（仅本地访问）

VPS部署

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

# 下载部署脚本
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配置文件：

# 使用HTTP传输的开发模式
docker-compose -f docker-compose.dev.yml up

# 带有Redis Commander的开发模式
docker-compose -f docker-compose.dev.yml --profile tools up

# 用于桌面集成的STDIO传输
docker-compose -f docker-compose.dev.yml --profile stdio up

# 带有监控的生产模式
docker-compose -f docker-compose.prod.yml up -d

🔧 技术细节

架构

本服务器采用模块化、适用于生产环境的架构：

核心组件：

服务器层 (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传输层。
监控：集成Prometheus指标和Grafana仪表盘。
反向代理：使用Nginx进行反向代理，支持SSL和速率限制。

成本估算

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

文本输入：每100万个令牌约5美元。
图像输出：每100万个令牌约40美元（每张图像约1750个令牌）。
典型成本：每次图像生成约0.07美元。

错误处理

全面的错误处理包括：

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

安全

安全功能包括：

保护OpenAI API密钥。
输入验证和清理。
文件系统访问控制。
速率限制保护。
日志中不暴露凭证。

📄 许可证

本项目采用MIT许可证，详情请参阅LICENSE文件。

贡献指南

分叉仓库。
创建功能分支。
进行更改。
为新功能添加测试。
运行测试套件。
提交拉取请求。

支持

如果遇到问题或有疑问：

查看故障排除指南。
查看常见问题。
在GitHub上创建问题。

可视化展示

实际使用场景

Claude Desktop与图像生成MCP Claude Desktop通过MCP集成无缝生成图像

生成示例

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

使用案例与应用场景

🎯 内容创作工作流程

博主和作家：直接在写作工具中生成自定义插图。
社交媒体经理：在聊天界面内创建特定平台的图形，无需切换工具。
营销团队：在头脑风暴会议期间快速原型化视觉概念。
教育工作者：按需生成教学材料和视觉辅助工具。

🚀 开发与设计

UI/UX设计师：在设计讨论期间快速生成原型。
前端开发人员：在开发环境中使用占位符和概念图像。
技术文档撰写人员：为文档生成自定义图表和插图。
产品经理：在任何基于LLM的工具中进行视觉概念沟通。

🏢 企业集成

客户支持：生成可视化解释和指南。
销售团队：根据客户需求定制演示材料。
培训项目：在对话界面中创建视觉学习材料。
内部工具：为现有的基于LLM的应用程序添加图像生成功能。

🎨 创意产业

游戏开发者：进行概念艺术和资产构思。
电影和媒体：进行故事板和概念可视化。
建筑行业：快速生成视觉参考和情绪板。
广告行业：进行广告活动概念开发。

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

AI集成的未来

模型上下文协议代表了向标准化AI工具集成的范式转变。随着越来越多的LLM客户端采用MCP支持，像本服务器这样的工具将在整个生态系统中发挥越来越重要的作用，提供通用的功能。

当前MCP采用情况：

✅ Claude Desktop（Anthropic） - 全面支持MCP。
✅ Continue.dev - 集成了MCP的VS Code扩展。
✅ Zed Editor - 内置MCP支持，适用于编码工作流程。
🚀 不断发展的生态系统 - 新的客户端不断采用MCP。

愿景：未来，AI功能将变得模块化、可互操作且由用户控制，而不是局限于特定平台。

🌟 构建通用AI生态系统

通过模型上下文协议的力量，在所有平台上实现高级AI功能的民主化。一台服务器，无限可能。