# 即梦AI图像生成 MCP 服务
这是一个基于 [FastMCP](https://github.com/jlowin/fastmcp) 框架的 MCP (Model Context Protocol) 服务，用于调用即梦AI图像生成API。
---
**📚 快速链接：**
- 🚀 [快速开始指南](QUICKSTART.md) - 5分钟快速测试
- 🧪 [测试指南](TESTING.md) - 详细的测试方法说明
- 📖 完整文档（当前页面）
---
## 功能特性
- 🎨 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. 安装依赖：
```bash
pip install -r requirements.txt
```
## 配置
设置环境变量 `JIMENG_TOKEN`，这是即梦平台的认证token（sessionid）：
```bash
export JIMENG_TOKEN="your_session_id_here"
```
或者在运行时指定：
```bash
JIMENG_TOKEN="your_token" python server.py
```
## 使用方法
### 方式 1: 快速测试（推荐）
使用测试脚本快速验证功能：
```bash
# 1. 设置token
export JIMENG_TOKEN="your_session_id_here"
# 2. 运行测试
python test_client.py
# 3. 查看生成的图片
ls -lh ./test_output/
```
详细测试说明请查看 [TESTING.md](TESTING.md)
### 方式 2: 作为MCP服务使用
#### 在 Claude Desktop 中配置：
编辑配置文件：
- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
- Windows: `%APPDATA%\Claude\claude_desktop_config.json`
添加以下配置：
```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: 在代码中直接使用
```python
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
**示例：**
```python
generate_image(
prompt="秋日街道旁的时尚店铺，一位长发微卷的亚洲女性站在橱窗边",
save_folder="./output/autumn_fashion",
width=960,
height=1024
)
```
**返回：**
```json
{
"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
### 测试
直接运行服务器进行测试：
```bash
JIMENG_TOKEN="your_token" python server.py
```
然后使用MCP客户端（如Claude Desktop）连接测试。
## 故障排查
### Token未设置
**错误：** `JIMENG_TOKEN环境变量未设置`
**解决：** 确保设置了环境变量：
```bash
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 文档](https://github.com/jlowin/fastmcp)
- [MCP 协议说明](https://modelcontextprotocol.io/)
- 即梦AI官网: https://jimeng.jianying.com
