imgenx-mcp 0.3.0

AI Image/Video Generation MCP Server with OSS Upload - Powered by Doubao API

一站式 AI 图片/视频生成与处理套件，支持文本/图生图、文本/图生视频、图片分析与常用编辑（裁剪、缩放、转换、调参），并集成阿里云 OSS 上传。可作为命令行工具或 MCP Server 使用

https://github.com/user-attachments/assets/92749d6f-727e-4874-a008-6ded8b4d9e7b

功能特性

• 文本生成图片: 根据文本描述生成图片
• 图片生成图片: 基于输入图片和文本描述生成新图片
• 文本/图片生成视频: 支持提示词生成视频，或基于首尾帧生成视频
• 图片下载/视频下载: 将生成的图片或视频URL下载并保存到本地
• 图片处理工具: 提供完整的图片处理功能
  • 图片信息获取: 查看图片格式、尺寸、模式等信息
  • 图片裁剪: 按指定区域裁剪图片（支持小数比例坐标）
  • 尺寸调整: 调整图片大小，支持保持宽高比
  • 格式转换: 支持PNG、JPEG、JPG、WEBP格式转换
  • 图像调整: 调整亮度、对比度、饱和度
  • 图片粘贴: 将图片粘贴到背景图片的指定位置
• 图片理解与分析: 基于视觉模型分析图片内容，输出结构化或文本结果
• ☁️ 阿里云 OSS 上传: 直接上传文件到阿里云 OSS，支持 CDN 加速（新增）
  • upload_to_oss: 上传本地文件到 OSS
  • download_and_upload_to_oss: 下载 URL 并直接上传到 OSS
• 多种分辨率支持: 支持 1K、2K、4K 分辨率以及多种自定义像素尺寸
• 插件化架构: 基于工厂模式设计，支持扩展新的图片生成服务提供商
• MCP 协议支持: 兼容 Model Context Protocol 标准

当前支持的服务提供商

• 豆包 (Doubao): 基于火山引擎的图片生成服务

安装

配置环境变量

# 图片视频生成模型配置
export IMGENX_IMAGE_MODEL="doubao:doubao-seedream-4-0-250828"   # 图片生成模型
export IMGENX_VIDEO_MODEL="doubao:doubao-seedance-1-0-pro-fast-251015" # 视频生成模型（可选）
export IMGENX_ANALYZER_MODEL="doubao:doubao-seed-1-6-vision-250815"   # 图片分析模型（可选）
export IMGENX_API_KEY="your_api_key"

# 阿里云 OSS 配置（可选，用于文件上传）
export OSS_ACCESS_KEY_ID="your_oss_access_key_id"
export OSS_ACCESS_KEY_SECRET="your_oss_access_key_secret"
export OSS_BUCKET="your_bucket_name"
export OSS_ENDPOINT="oss-cn-shanghai.aliyuncs.com"
export OSS_CDN_URL="https://your-cdn-domain.com/"

或写入 .env 文件中

安装步骤

方式一：pip 安装（推荐）

pip install imgenx-mcp

方式二：从源码安装

git clone https://github.com/helios123/imgenx-mcp.git
cd imgenx-mcp
pip install -e .

使用方法

作为命令行运行

# 生成图片（文本或图生图）
imgenx image "一只在云上飞翔的猫"
imgenx image "一只在云上飞翔的猫" --size 2K
imgenx image "一只在云上飞翔的猫" --size 2048x2048 --output test.jpg
imgenx image "一只在云上飞翔的猫" --images test.jpg --size 2048x2048 --output out_dir/

# 生成视频（文本或基于首尾帧）
imgenx video "一个人在运动" --resolution 720p --ratio 16:9 --duration 5 --output video.mp4
imgenx video "一个人在运动" --first_frame logo.jpg --resolution 720p --ratio 16:9 --duration 5 --output video.mp4

作为 MCP 服务器运行

标准输入输出模式 (stdio) - 推荐

配置文件位置：

• Windows: %APPDATA%\Claude\claude_desktop_config.json
• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

配置示例（使用 uvx，无需安装）：

{
  "mcpServers": {
    "imgenx": {
      "command": "uvx",
      "args": ["imgenx-mcp"],
      "env": {
        "IMGENX_IMAGE_MODEL": "doubao:doubao-seedream-4-0-250828",
        "IMGENX_VIDEO_MODEL": "doubao:doubao-seedance-1-0-pro-fast-251015",
        "IMGENX_ANALYZER_MODEL": "doubao:doubao-seed-1-6-vision-250815",
        "IMGENX_API_KEY": "your_api_key_here",
        "OSS_ACCESS_KEY_ID": "your_oss_key",
        "OSS_ACCESS_KEY_SECRET": "your_oss_secret",
        "OSS_BUCKET": "your_bucket",
        "OSS_ENDPOINT": "oss-cn-shanghai.aliyuncs.com",
        "OSS_CDN_URL": "https://your-cdn.com/"
      },
      "timeout": 600
    }
  }
}

配置示例（使用已安装的包）：

{
  "mcpServers": {
    "imgenx": {
      "command": "python",
      "args": ["-m", "imgenx.main"],
      "env": {
        "IMGENX_IMAGE_MODEL": "doubao:doubao-seedream-4-0-250828",
        "IMGENX_API_KEY": "your_api_key_here"
      },
      "timeout": 600
    }
  }
}

配置后重启 Claude Desktop 即可使用。

HTTP 服务器模式

imgenx server --transport streamable-http --host 0.0.0.0 --port 8000
imgenx server --transport streamable-http --no_tools text_to_video image_to_video  # 禁用视频生成工具

{
  "mcpServers": {
    "imgenx-mcp": {
      "url": "http://127.0.0.1:8000/mcp",
      "headers": {
        "IMGENX_IMAGE_MODEL": "doubao:doubao-seedream-4-0-250828",
        "IMGENX_VIDEO_MODEL": "doubao:doubao-seedance-1-0-pro-fast-251015",
        "IMGENX_ANALYZER_MODEL": "doubao:doubao-seed-1-6-vision-250815",
        "IMGENX_API_KEY": "api-key"
      },
      "timeout": 600
    }
  }
}

可用工具

1. text_to_image

根据文本描述生成图片。

2. image_to_image

基于输入图片和文本描述生成新图片。

3. download

下载图片或视频到本地。

4. get_image_info

获取图片信息。

5. crop_image

裁剪图片。

6. resize_image

调整图片尺寸。

7. convert_image

转换图片格式。

8. adjust_image

调整图片的亮度、对比度和饱和度。

9. text_to_video

根据文本提示生成视频。

10. image_to_video

基于首帧与可选尾帧生成视频。

11. analyze_image

分析图片内容，返回结构化或文本结果。

12. paste_image

将图片粘贴到背景图片的指定位置。

13. upload_to_oss (新增)

上传本地文件到阿里云 OSS。

14. download_and_upload_to_oss (新增)

下载 URL 并直接上传到阿里云 OSS（无需本地保存）。

项目结构

imgenx-mcp-server/
├── imgenx/
│   ├── server.py                  # MCP 服务器主文件（工具定义与运行）
│   ├── factory.py                 # 预测器工厂（图片/视频/分析）
│   ├── operator.py                # 图片处理操作模块
│   ├── main.py                    # CLI 入口（imgenx）
│   ├── script.py                  # 命令行生成图片/视频脚本
│   └── predictor/
│       ├── base/
│       │   ├── base_image_generator.py   # 基础图片生成器接口
│       │   ├── base_video_generator.py   # 基础视频生成器接口
│       │   └── base_image_analyzer.py    # 基础图片分析器接口
│       └── generators/
│           ├── doubao_image_generator.py   # 豆包图片生成器实现
│           ├── doubao_video_generator.py   # 豆包视频生成器实现
│           └── doubao_image_analyzer.py    # 豆包图片分析器实现
├── pyproject.toml                 # 项目配置（入口脚本等）
├── uv.lock                        # 依赖锁（可选）
└── README.md                      # 项目说明

扩展新的服务提供商

要扩展新的服务提供商：

1. 在 imgenx/predictor/generators/ 目录下创建实现文件，命名规范：

   • 图片生成器：{provider}_image_generator.py
   • 视频生成器（可选）：{provider}_video_generator.py
   • 图片分析器（可选）：{provider}_image_analyzer.py

2. 实现 BaseImageGenerator 接口：

from typing import List, Dict
from imgenx.predictor.base.base_image_generator import BaseImageGenerator

class ProviderImageGenerator(BaseImageGenerator):
    def __init__(self, model: str, api_key: str):
        self.model = model
        self.api_key = api_key
        # 其他初始化代码
    
    def text_to_image(self, prompt: str, size: str) -> List[Dict[str, str]]:
        # 实现文本生成图片逻辑
        # 返回格式: [{"url": "图片URL"}]
        pass
    
    def image_to_image(self, prompt: str, images: List[str], size: str) -> List[Dict[str, str]]:
        # 实现图片生成图片逻辑（可选）
        # 返回格式: [{"url": "图片URL"}]
        pass

3. 工厂类会自动发现并加载新的实现（基于文件名），模型字符串需为 provider:model 格式，例如：doubao:doubao-seedream-4-0-250828

依赖项

• fastmcp>=2.12.4: MCP 协议实现
• python-dotenv>=1.1.1: 环境变量加载
• volcengine-python-sdk[ark]>=4.0.22: 火山引擎 SDK（豆包服务）
• requests>=2.25.0: HTTP 请求库（用于图片下载）
• pillow>=12.0.0: 图片处理库（用于图片编辑操作）
• oss2>=2.19.1: 阿里云 OSS SDK（用于文件上传）

使用示例

在 Claude Desktop 中使用

配置完成后，在 Claude 中可以直接使用自然语言：

生成一只小猫在天上飞的图片

生成一个日落海滩的视频，5秒，1080p

把刚生成的图片上传到 OSS

完整工作流示例

1. 生成图片

   生成一只可爱的小猫在蓝天白云中飞翔的图片
   

2. 上传到 OSS

   把这张图片上传到 OSS
   

   返回 CDN 地址，可直接访问和分享。

相关文档

• OSS 上传使用说明
• 性能优化说明

更新日志

v0.3.0 (当前版本)

新增功能

• ☁️ 阿里云 OSS 上传: 新增 upload_to_oss 和 download_and_upload_to_oss 工具
• CDN 加速支持: 上传后自动返回 CDN 加速地址
• 完整工作流: 生成图片/视频 -> 上传 OSS -> 获取 CDN URL

性能优化

• 移除不必要的文件验证步骤，提升上传速度约 35%
• 优化文件上传流程，减少网络请求

文档完善

• 新增 OSS 上传使用说明文档
• 新增性能优化说明文档
• 完善 Claude Desktop 配置示例

v0.2.3

新增功能

• 图片粘贴: 新增 paste_image 工具，支持将图片粘贴到背景图片的指定位置
• 工具控制: 新增 --no_tools 参数，支持在运行 MCP 服务器时禁用特定工具

功能优化

• 完善图片处理工具集，增强图片编辑能力

v0.2.0

新增功能

• 视频生成: 支持 text_to_video 与 image_to_video 两种方式
• 图片分析: 新增 analyze_image 工具，支持视觉模型分析
• 图片处理工具集完善: get_image_info、crop_image（比例坐标）、resize_image、convert_image、adjust_image

技术改进

• 工厂模式统一图片/视频/分析三类预测器的发现与加载
• 环境变量分离为 IMGENX_IMAGE_MODEL、IMGENX_VIDEO_MODEL、IMGENX_ANALYZER_MODEL
• MCP 工具集扩展，HTTP 服务器提供 /health、/healthy 健康检查路由
• 支持本地文件与 URL 两种图片输入方式；下载工具统一图片/视频

许可证

本项目的许可证信息请查看项目仓库。

贡献

欢迎提交 Issue 和 Pull Request 来改进这个项目。

联系方式

• GitHub: @helios123
• Issues: 提交问题
• 原作者 Email: [e-mail]