Gpt Image Mcp

Gpt Image Mcp

内容 Python

🚀 图像生成MCP服务器

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

🚀 快速开始

前提条件

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

安装步骤

  1. 克隆并设置项目：
git clone 
cd image-gen-mcp
uv sync

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

  1. 配置环境：
cp .env.example .env
# 编辑.env文件并添加你的API密钥：
# - PROVIDERS__OPENAI__API_KEY用于OpenAI模型
# - PROVIDERS__GEMINI__API_KEY用于Gemini模型（可选）
  1. 测试设置：
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 
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文件。

贡献指南

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

支持

如果遇到问题或有疑问：

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

可视化展示

实际使用场景

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

生成示例

默认排序 时间排序

0 个评论

  • 0 关注
  • 0 收藏，11 浏览
  • system 提出于 2025-09-30 21:18

相似服务问题

热议话题 »