即梦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        # 项目文档

安装

1. 克隆或下载本项目

2. 安装依赖：

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"
}

工作流程：

1. 提交图像生成请求
2. 自动轮询等待生成完成（最多3分钟，每3秒轮询一次）
3. 获取生成的图片URL列表
4. 依次下载所有图片
5. 按顺序保存为 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     │
└─────────────────┘

技术细节

核心功能

1. 请求签名生成 (header_util.py)

   • 动态生成设备ID和WebID
   • 计算请求签名(MD5)
   • 构建完整的HTTP请求头

2. 图像生成服务 (service.py)

   • 构建复杂的draft_content JSON结构
   • 处理图像尺寸和比例计算
   • 管理UUID和随机种子生成
   • 封装API调用逻辑
   • 轮询机制：自动轮询检查生成状态
   • 下载功能：批量下载并保存图片

3. MCP服务器 (server.py)

   • 使用FastMCP框架
   • 提供标准化的工具接口
   • 环境变量管理
   • 一站式生成和下载流程

完整工作流程

1. 提交生成请求

   • 生成唯一的submit_id、draft_id等UUID
   • 根据prompt和参数构建draft_content
   • 使用header_util生成签名和请求头
   • 发送POST请求到 /mweb/v1/aigc_draft/generate

2. 轮询生成结果

   • 使用submit_id轮询 /mweb/v1/get_history_by_ids 接口
   • 每3秒检查一次状态
   • 最多轮询60次（总计3分钟）
   • 状态码：1=生成中, 2=成功, 3=失败

3. 下载图片

   • 从返回结果中提取图片URL列表
   • 依次下载每张图片
   • 按照顺序命名为 01.jpg, 02.jpg, 03.jpg 等
   • 保存到指定文件夹

4. 返回结果

   • 返回包含图片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请求失败

可能原因：

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

解决：

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

注意事项

⚠️ 重要提示：

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

许可证

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

相关链接

• FastMCP 文档
• MCP 协议说明
• 即梦AI官网: https://jimeng.jianying.com