MCP Image Generation Server

MCP 图像生成服务

一个使用多个 AI 提供商生成图像的模型上下文协议（MCP）服务，支持 Tencent Hunyuan、OpenAI GPT Image 和 Doubao API。

版本：0.2.0

功能

🎯 支持多个 API 提供商

• Tencent Hunyuan：支持 18 种艺术风格，并针对中文进行了优化
• OpenAI GPT Image：高质量图像生成，并针对英文进行了优化
• Doubao（ByteDance）：兼顾质量与速度，支持 12 种风格

🚀 核心功能

• 根据文本描述生成图像
• 支持不同提供商的多种图像风格
• 支持不同图像分辨率
• 使用负面提示词排除不需要的元素
• 智能选择和管理提供商
• 统一的参数格式，并支持提供商专属选项

🌐 传输模式（v0.2.0 新增）

• stdio 传输：本地 IDE 集成（Cursor、Windsurf）
• HTTP 传输：远程访问和企业部署
  • 支持多个客户端并发连接
  • Bearer Token 身份验证
  • 会话管理
  • RESTful API 端点
  • 适用于云部署和远程访问

为什么使用 HTTP 传输？ 0.2.0 版新增了 Streamable HTTP 支持（截至 2024-11-05 的 MCP 官方标准），以实现：

• 远程访问：Claude 远程 MCP 需要公开的 HTTP 端点（stdio 仅适用于本地）
• 企业部署：集中式服务部署，支持多个客户端并发连接
• 云原生：兼容容器、Kubernetes 和负载均衡器

注意：此处使用的是 Streamable HTTP（POST/GET/DELETE），而非已弃用的纯 SSE 方案。为保持兼容性，仍保留 SSE，但推荐使用 Streamable HTTP 标准。

🔧 智能提供商管理

• 自动检测可用的 API 提供商
• 支持指定特定提供商或自动选择
• 统一的错误处理和重试机制
• 灵活的参数格式：provider:style 和 provider:resolution

安装

使用 UV（推荐）

UV 是一款快速、现代的 Python 包管理器。推荐使用方式：

# Install UV (Windows)
curl -sSf https://astral.sh/uv/install.ps1 | powershell

# Install UV (macOS/Linux)
curl -sSf https://astral.sh/uv/install.sh | bash

# Clone the project and enter the directory
cd path/to/image-gen-mcp-server

# Create a UV virtual environment
uv venv
# Or specify an environment name
# uv venv my-env-name

# Activate the virtual environment (Windows)
.venv\Scripts\activate
# Activate the virtual environment (macOS/Linux)
source .venv/bin/activate

# Install dependencies (recommended)
uv pip install -e .

# Or use the lock file for exact versions
uv pip install -r requirements.lock.txt

使用传统 pip

如果你更喜欢传统的 pip：

# Create a virtual environment
python -m venv venv
# Activate the virtual environment (Windows)
venv\Scripts\activate
# Activate the virtual environment (macOS/Linux)
source venv/bin/activate

# Install dependencies
pip install -e .
# Or use the lock file
pip install -r requirements.lock.txt

环境设置

在项目根目录创建 .env 文件。所有可用选项请参阅 .env.example。

基本配置

# Image save directory
MCP_IMAGE_SAVE_DIR=./generated_images
# Public base URL for generated image links (HTTP mode, optional but recommended)
# MCP_PUBLIC_BASE_URL=https://mcp.your-domain.com
# Metadata TTL for get_image_data cache (seconds)
# MCP_IMAGE_RECORD_TTL=86400
# Max bytes allowed in get_image_data base64 response
# MCP_GET_IMAGE_DATA_MAX_BYTES=10485760

# API Provider Credentials (configure at least one)
TENCENT_SECRET_ID=your_tencent_secret_id
TENCENT_SECRET_KEY=your_tencent_secret_key
OPENAI_API_KEY=your_openai_api_key
DOUBAO_API_KEY=your_doubao_api_key
# Optional but recommended when multiple providers are configured
# MCP_DEFAULT_PROVIDER=openai

传输配置（可选）

# Transport mode: stdio (default, for local IDE) or http (for remote access)
MCP_TRANSPORT=stdio

# HTTP transport settings (only needed for HTTP mode)
MCP_HOST=127.0.0.1
MCP_PORT=8000

# Authentication (recommended for HTTP mode)
MCP_AUTH_TOKEN=your-secure-random-token

用法

🔄 传输模式

此服务支持两种传输模式：

功能	stdio 传输	HTTP 传输
使用场景	本地 IDE 集成	远程访问、企业部署
连接方式	子进程通信	HTTP/HTTPS 网络
多客户端	❌ 单个客户端	✅ 多个客户端并发连接
远程访问	❌ 不支持	✅ 支持
身份验证	无需	Bearer Token
部署方式	简单	适用于云环境

🚀 快速开始

统一入口点（推荐）

# Method 1: Run as module (recommended)
python -m mcp_image_server

# Method 2: Use entry script
./mcp-server

# Method 3: After pip install
mcp-image-server

统一服务将自动使用 .env 文件中指定的传输模式：

• MCP_TRANSPORT=stdio → 用于 IDE 集成的本地 stdio 模式
• MCP_TRANSPORT=http → 用于远程访问的 HTTP 服务模式

📡 HTTP 传输模式

如需远程访问和企业部署，请使用 HTTP 传输：

1. 配置 HTTP 模式

# Set in .env file
MCP_TRANSPORT=http
MCP_HOST=127.0.0.1
MCP_PORT=8000
MCP_AUTH_TOKEN=your-secure-token  # Optional but recommended

2. 启动 HTTP 服务

python -m mcp_image_server

服务将在 http://127.0.0.1:8000 上启动，并提供以下端点：

• GET /health - 健康检查
• POST /mcp/v1/messages - 发送 JSON-RPC 消息
• GET /mcp/v1/messages - 订阅 SSE 事件
• DELETE /mcp/v1/messages - 关闭会话
• GET /images/{filename} - 提供生成的图像文件

对于 HTTP 客户端，generate_image 工具会返回 images[].url。
如果服务通过反向代理或公共域名对外提供，请设置 MCP_PUBLIC_BASE_URL，以确保 URL 可从外部访问。 /images/* 有意设置为公开访问，这样即使启用了 MCP API 身份验证，浏览器或前端也能正常渲染图像。

推荐的 Agent 工作流：

1. 调用 generate_image，获取可渲染的图像，以及稳定的 image_id/url。
2. 仅在需要可编程处理的 base64 文本时，调用 get_image_data(image_id=...)。

3. 测试 HTTP 服务

# Check server health
curl http://127.0.0.1:8000/health

# Run comprehensive tests
python test_mcp_server.py

# Test with API key for actual image generation
python test_mcp_server.py --with-api

4. 使用 HTTP 客户端

# Run example client
python example_http_client.py basic       # Explore server capabilities
python example_http_client.py generate    # Generate images (requires API key)

有关 HTTP 传输的详细文档，请参阅 HTTP_TRANSPORT_GUIDE.md

MCP 服务成功运行的截图：

连接到服务

你可以从兼容 MCP 的客户端连接（目前推荐使用 cursor）。服务提供以下功能：

资源

• styles://list - 列出所有可用的图像风格
• resolutions://list - 列出所有可用的图像分辨率

工具

• generate_image - 根据提示词、风格和分辨率生成图像（OpenAI 还支持 background/output_format/output_compression/moderation）
• get_image_data - 根据 image_id 获取先前生成图像的 base64 文本

提示词

• image_generation_prompt - 创建图像生成提示词模板

🎨 多 API 使用示例

基本用法

# Auto-select best available provider
generate_image(prompt="A cute cat in a garden")

# Specify a particular provider
generate_image(prompt="A cute cat", provider="openai")
generate_image(prompt="一只可爱的小猫", provider="hunyuan")
generate_image(prompt="Cute kitten", provider="doubao")

高级参数用法

# Use provider-specific styles and resolutions
generate_image(
    prompt="Cyberpunk city skyline", 
    style="hunyuan:saibopengke", 
    resolution="hunyuan:1024:768"
)

# Mix provider selection with standard parameters
generate_image(
    prompt="Fantasy magical forest",
    provider="doubao",
    style="fantasy",
    resolution="1024x768",
    negative_prompt="low quality, blurry"
)

# OpenAI with high-resolution output
generate_image(
    prompt="Artistic portrait of a musician",
    provider="openai",
    style="artistic",
    resolution="1536x1024"
)

📊 支持的提供商和参数

Tencent Hunyuan

• 风格：18 种选项，包括 riman、xieshi、shuimo、saibopengke、youhua
• 分辨率：8 种选项，从 768:768 到 1280:720
• 特点：针对中文优化，艺术风格丰富

OpenAI GPT Image

• 风格：12 种选项，包括 natural、vivid、realistic、artistic、anime
• 分辨率：4 种选项：1024x1024、1536x1024、1024x1536、auto
• 高级选项：background、output_format、output_compression、moderation（通过 MCP 客户端使用）
• 特点：输出质量高，针对英文优化

Doubao (ByteDance)

• 风格：12 种选项，包括 general、anime、chinese_painting、cyberpunk
• 分辨率：取决于模型（根据已配置的模型或回退模型自动验证）
• 特点：质量与速度均衡

Cursor 集成

有关集成设置详情和配置 JSON 示例，请参阅：

• docs/VSCODE_INTEGRATION.md

建议至少设置以下环境变量：

• MCP_IMAGE_SAVE_DIR
• 你实际使用的提供商凭据： TENCENT_SECRET_ID + TENCENT_SECRET_KEY、OPENAI_API_KEY、DOUBAO_API_KEY

可选的提供商/模型控制项：

• OPENAI_BASE_URL、OPENAI_MODEL
• DOUBAO_ENDPOINT、DOUBAO_MODEL、DOUBAO_FALLBACK_MODEL
• MCP_DEFAULT_PROVIDER（启用多个提供商时建议设置）

在运行期间更改 .env 中的模型或默认提供商值后，请调用 reload_config。

🧪 测试

项目包含全面的测试工具：

协议测试（无需 API 密钥）

# Test MCP protocol functionality without API keys
python test_mcp_server.py

此测试涵盖：

• ✅ 健康检查端点
• ✅ MCP 初始化握手
• ✅ 工具列表
• ✅ 资源列表与读取
• ✅ 提示词列表
• ✅ 会话管理

功能测试（需要 API 密钥）

# Test actual image generation with configured providers
python test_mcp_server.py --with-api

此测试还涵盖：

• ✅ 使用 OpenAI 实际生成图像
• ✅ 使用 Hunyuan 实际生成图像
• ✅ 使用 Doubao 实际生成图像

注意：运行功能测试前，必须在 .env 中至少配置一个 API 密钥。

故障排除

常见问题

• 确保正确设置环境变量
• 检查路径中是否包含空格；如有需要，请使用引号
• 确保已激活虚拟环境（如果使用）
• 尝试直接运行服务脚本以检查错误
• 使用 uv --version 检查 UV 环境

HTTP 传输问题

• 连接被拒绝：确保服务在正确的主机和端口上运行
• 401 未授权：检查 MCP_AUTH_TOKEN 配置
• 404 未找到会话：重新初始化连接以获取新的会话 ID
• 没有可用的提供方：在 .env 中至少配置一个 API 提供方

详细的故障排查信息，请参阅 HTTP_TRANSPORT_GUIDE.md

前端演示

如需前端集成示例，请参阅 web-design-demo/。 此示例展示了如何使用 Cursor IDE 开发实际项目，你可以通过我们的 MCP 工具 🛠️，直接在开发环境中生成和管理图像。无需在不同的图像生成工具之间切换，也无需离开 IDE——所有操作都可以直接在开发工作流中完成 ✨。

• 演示网页截图

API 参考

多 API 架构

该项目现已通过统一接口支持多个图像生成 API：

支持的 API

1. 腾讯混元图像生成 API（原有）
2. OpenAI GPT Image API（新增）
3. 豆包图像生成 API（新增）

统一 MCP 资源

• providers://list - 列出所有可用的提供方
• styles://list - 列出所有提供方的所有风格
• resolutions://list - 列出所有提供方的所有分辨率
• styles://provider/{provider_name} - 获取指定提供方的风格
• resolutions://provider/{provider_name} - 获取指定提供方的分辨率

增强的 MCP 工具

• generate_image - 通过智能路由实现多提供方图像生成
• get_image_data - 根据 ID 检索已生成图像的 Base64 文本数据
• reload_config - 在不重启进程的情况下，重新加载运行时配置/模型（仅限安全子集）

腾讯混元图像生成 API

该项目最初使用腾讯混元图像生成 API，并继续提供支持。以下是相关要点：

API 端点

• 域名：hunyuan.tencentcloudapi.com
• 区域：ap-guangzhou（目前仅支持广州区域）
• 默认 API 速率限制：每秒 20 个请求
• 并发任务：默认一次 1 个任务

任务流程

1. 提交任务：提交包含文本描述的异步图像生成任务
2. 查询任务：使用任务 ID 获取任务状态和结果
3. 结果 URL：生成的图像 URL 有效期为 1 小时

如需详细的 API 文档和定价信息，请参阅：

• API 文档
• 定价详情

OpenAI GPT Image API

API 特性

• 高质量图像生成
• 自动优化提示词
• 多种风格选项
• 支持高分辨率输出

豆包 API（字节跳动）

API 特性

• 字节跳动自有的图像生成模型
• 兼顾质量与速度
• 支持中文和英文提示词
• 多种艺术风格

路线图

• 版本 0.2.0（当前）

  • ✅ 腾讯混元图像生成 API
  • ✅ 集成 OpenAI GPT Image API
  • ✅ 集成豆包 API
  • ✅ 多提供商管理系统
  • ✅ 智能提供商选择
  • ✅ 统一参数接口
  • ✅ 使用 Streamable HTTP 协议的 HTTP 传输
  • ✅ 支持远程访问
  • ✅ 支持多个客户端并发连接
  • ✅ Bearer Token 身份验证
  • ✅ 会话管理
  • ✅ 全面的测试套件

• 未来计划

  • 支持更多主流文生图模型 API，包括：
    • Qwen-Image（Qwen/Wan 系列）
    • 开源模型 API 服务（例如：FLUX、SDXL/SD3.5）
  • 高级功能：
    • 图像编辑与修改
    • 批量图像生成
    • 风格迁移功能
    • 支持自定义模型微调
  • 增强 MCP 集成：
    • 实时生成进度
    • 图像历史记录与管理
    • 高级提示词模板

欢迎社区贡献更多模型集成和新功能！

兼容性

• stdio：已在 Cursor 和 Windsurf 中验证。
• HTTP（Streamable HTTP）：可与支持 HTTP 传输的 MCP 客户端配合使用。
• 对于其他客户端／环境，兼容性取决于客户端侧的 MCP 实现。

贡献

欢迎各种形式的贡献！以下是一些可以提供帮助的方式：

• 🐛 报告 Bug 和问题
• 💡 提出新功能或改进建议
• 🔧 提交拉取请求
• 🎨 添加对更多图像生成模型的支持

开始贡献

1. Fork 此仓库
2. 创建功能分支（git checkout -b feature/AmazingFeature）
3. 提交更改（git commit -m 'feat: add some AmazingFeature'）
4. 推送到该分支（git push origin feature/AmazingFeature）
5. 发起拉取请求

请确保酌情更新测试，并遵循现有代码风格。

感谢你有兴趣让这个项目变得更好！