即梦AI图像生成 MCP 服务

这是一个基于 FastMCP 框架的 MCP (Model Context Protocol) 服务，用于调用即梦AI图像生成API。

📚 快速链接：

🚀 快速开始指南 - 5分钟快速测试
🧪 测试指南 - 详细的测试方法说明
📖 完整文档（当前页面）

功能特性

🎨 AI图像生成
🔄 自动轮询等待生成完成
📥 自动下载并保存图片到指定文件夹
📝 按顺序命名文件（01.jpg, 02.jpg等）
🔧 完整的参数配置（尺寸、模型、提示词等）
🔐 安全的token管理
📊 详细的响应结果

项目结构

jimeng-mcp/
├── server.py         # FastMCP服务器主文件
├── service.py        # 图像生成服务核心逻辑
├── header_util.py    # HTTP请求头生成工具
├── requirements.txt  # Python依赖
├── curl.sh          # 原始curl命令参考
└── README.md        # 项目文档

安装

克隆或下载本项目
安装依赖：

pip install -r requirements.txt

配置

设置环境变量 JIMENG_TOKEN，这是即梦平台的认证token（sessionid）：

export JIMENG_TOKEN="your_session_id_here"

或者在运行时指定：

JIMENG_TOKEN="your_token" python server.py

使用方法

方式 1: 快速测试（推荐）

使用测试脚本快速验证功能：

# 1. 设置token
export JIMENG_TOKEN="your_session_id_here"

# 2. 运行测试
python test_client.py

# 3. 查看生成的图片
ls -lh ./test_output/

详细测试说明请查看 TESTING.md

方式 2: 作为MCP服务使用

在 Claude Desktop 中配置：

编辑配置文件：

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

添加以下配置：

{
  "mcpServers": {
    "jimeng-image-generator": {
      "command": "python",
      "args": ["/absolute/path/to/jimeng-mcp/server.py"],
      "env": {
        "JIMENG_TOKEN": "your_session_id_here"
      }
    }
  }
}

重启 Claude Desktop 后即可使用。

方式 3: 在代码中直接使用

from service import create_service

token = "your_token"
service = create_service(token)

result = service.generate_image(
    prompt="秋日街道旁的时尚店铺",
    save_folder="./output",
    width=960,
    height=1024
)
print(result)

MCP工具

generate_image - 生成图像并保存

生成AI图像，自动轮询等待完成，下载并保存到指定文件夹。

参数：

prompt (str, 必需): 图像生成提示词，详细描述要生成的图像内容
save_folder (str, 必需): 图片保存文件夹路径（相对路径或绝对路径）
width (int, 可选): 图像宽度，默认1728
height (int, 可选): 图像高度，默认2304
model (str, 可选): 使用的模型，默认 high_aes_general_v40
negative_prompt (str, 可选): 负面提示词，描述不希望出现的内容
sample_strength (float, 可选): 采样强度(0-1)，默认0.5

示例：

generate_image(
    prompt="秋日街道旁的时尚店铺，一位长发微卷的亚洲女性站在橱窗边",
    save_folder="./output/autumn_fashion",
    width=960,
    height=1024
)

返回：

{
  "success": true,
  "submit_id": "9fff4adc-ed58-479c-9d99-5a2fee0bb097",
  "image_urls": [
    "https://...",
    "https://...",
    "https://..."
  ],
  "saved_files": [
    "./output/autumn_fashion/01.jpg",
    "./output/autumn_fashion/02.jpg",
    "./output/autumn_fashion/03.jpg"
  ],
  "total_images": 3,
  "save_folder": "./output/autumn_fashion"
}

工作流程：

提交图像生成请求
自动轮询等待生成完成（最多3分钟，每3秒轮询一次）
获取生成的图片URL列表
依次下载所有图片
按顺序保存为 01.jpg, 02.jpg, 03.jpg 等

MCP资源

jimeng://config - 查看配置信息

获取当前服务配置信息，包括token状态、默认参数等。

图像尺寸建议

根据小红书等平台的推荐尺寸：

竖图（15:16）：1728x2304 或 960x1024 - 推荐用于小红书
方图（1:1）：1024x1024
横图（16:9）：1920x1080

服务架构

┌─────────────────┐
│   MCP Client    │
│   (Claude等)    │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│   server.py     │  FastMCP服务器
│   (MCP接口层)    │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│   service.py    │  业务逻辑层
│                 │  • 图像生成请求
│                 │  • 轮询生成结果
│                 │  • 下载图片
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│  header_util.py │  工具层
│   (签名生成)     │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│   即梦AI API    │
│  (外部服务)      │
│  • /generate    │
│  • /history     │
└─────────────────┘

技术细节

核心功能

请求签名生成 (header_util.py)
- 动态生成设备ID和WebID
- 计算请求签名(MD5)
- 构建完整的HTTP请求头
图像生成服务 (service.py)
- 构建复杂的draft_content JSON结构
- 处理图像尺寸和比例计算
- 管理UUID和随机种子生成
- 封装API调用逻辑
- 轮询机制：自动轮询检查生成状态
- 下载功能：批量下载并保存图片
MCP服务器 (server.py)
- 使用FastMCP框架
- 提供标准化的工具接口
- 环境变量管理
- 一站式生成和下载流程

完整工作流程

提交生成请求
- 生成唯一的submit_id、draft_id等UUID
- 根据prompt和参数构建draft_content
- 使用header_util生成签名和请求头
- 发送POST请求到 /mweb/v1/aigc_draft/generate
轮询生成结果
- 使用submit_id轮询 /mweb/v1/get_history_by_ids 接口
- 每3秒检查一次状态
- 最多轮询60次（总计3分钟）
- 状态码：1=生成中, 2=成功, 3=失败
下载图片
- 从返回结果中提取图片URL列表
- 依次下载每张图片
- 按照顺序命名为 01.jpg, 02.jpg, 03.jpg 等
- 保存到指定文件夹
返回结果
- 返回包含图片URL和本地路径的完整结果

开发

环境要求

Python 3.8+
fastmcp >= 0.1.0
requests >= 2.31.0

测试

直接运行服务器进行测试：

JIMENG_TOKEN="your_token" python server.py

然后使用MCP客户端（如Claude Desktop）连接测试。

故障排查

Token未设置

错误： JIMENG_TOKEN环境变量未设置

解决： 确保设置了环境变量：

export JIMENG_TOKEN="your_session_id"

API请求失败

可能原因：

Token过期或无效
网络连接问题
API参数错误

解决：

检查token是否有效
确认网络连接
查看详细错误信息

注意事项

⚠️ 重要提示：

Token安全：请勿在代码中硬编码token，使用环境变量
请求频率：遵守API的调用频率限制
提示词质量：更详细的提示词能生成更好的图像
图像尺寸：确保宽高比符合需求
轮询超时：图像生成最多等待3分钟，超时将返回错误
文件命名：图片自动按顺序命名（01.jpg, 02.jpg等），不会覆盖现有文件
网络稳定性：确保网络连接稳定，下载大图片可能需要时间

许可证

本项目仅供学习和研究使用。

Jimeng AI Image Generator