JinDaGe - modelscope-image-mcp MCP Details

article

README

🚀 ModelScope图像MCP服务器

ModelScope图像MCP服务器是一个基于Model Context Protocol（MCP）的服务器，借助ModelScope图像生成API来生成图像。该服务器可与AI助手无缝集成，支持通过自然语言提示词生成图像，具备强大的异步处理能力和本地文件管理功能。

🚀 快速开始

此服务器可直接在支持MCP的客户端（如Claude Desktop）中注册，无需手动安装，这得益于uvx的便捷性。

✨ 主要特性

利用ModelScope异步任务API实现异步图像生成。
定期轮询任务状态（每5秒一次，最长轮询2分钟）。
将生成的第一张图像保存到本地文件。
向MCP客户端返回任务状态和图像URL。
具备强大的错误处理机制和超时提示功能。
可通过uvx一键启动。

📦 安装指南

环境变量

服务器从以下环境变量中读取凭证：

MODELSCOPE_SDK_TOKEN

若缺少该环境变量，服务器将报错。可从以下链接获取令牌：https://modelscope.cn/my/myaccesstoken

Windows（cmd）设置方法：

set MODELSCOPE_SDK_TOKEN=your_token_here

PowerShell设置方法：

$env:MODELSCOPE_SDK_TOKEN="your_token_here"

Unix/macOS bash/zsh设置方法：

export MODELSCOPE_SDK_TOKEN=your_token_here

安装选项

选项1：PyPI（发布后推荐）

{
  "mcpServers": {
    "modelscope-image": {
      "command": "uvx",
      "args": ["modelscope-image-mcp"],
      "env": {
        "MODELSCOPE_SDK_TOKEN": "your_token_here"
      }
    }
  }
}

选项2：直接从GitHub安装

{
  "mcpServers": {
    "modelscope-image": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/zym9863/modelscope-image-mcp.git",
        "modelscope-image-mcp"
      ],
      "env": {
        "MODELSCOPE_SDK_TOKEN": "your_token_here"
      }
    }
  }
}

选项3：本地开发部署

git clone https://github.com/zym9863/modelscope-image-mcp.git
cd modelscope-image-mcp
uv sync

然后使用以下配置设置MCP客户端入口：

{
  "mcpServers": {
    "modelscope-image": {
      "command": "uvx",
      "args": ["--from", ".", "modelscope-image-mcp"],
      "env": { "MODELSCOPE_SDK_TOKEN": "your_token_here" }
    }
  }
}

本地快速测试

# 直接运行（本地部署）
uvx --from . modelscope-image-mcp

运行成功后，你将看到显示任务提交和轮询的日志信息。

💻 使用示例

基础用法

{
  "name": "generate_image",
  "arguments": {
    "prompt": "A serene mountain landscape at sunset"
  }
}

高级用法

{
  "name": "generate_image",
  "arguments": {
    "prompt": "A futuristic city with flying cars, cyberpunk style",
    "model": "Qwen/Qwen-Image",
    "size": "1024x1024",
    "output_filename": "cyberpunk_city.png",
    "output_dir": "./generated_images"
  }
}

创意提示词

艺术风格："in the style of Van Gogh"、"watercolor painting"、"digital art"
构图方式："close-up portrait"、"wide-angle landscape"、"bird's eye view"
光线效果："dramatic lighting"、"golden hour"、"studio lighting"
氛围基调："mysterious atmosphere"、"vibrant colors"、"minimalist design"

使用建议

明确描述：详细的提示词比模糊的提示词能生成更好的图像效果。
参考借鉴：提及特定的艺术风格、艺术家或时期。
大胆尝试：尝试不同的提示词变体，以找到最佳结果。
整理输出：使用具有描述性的文件名和有组织的目录。
关注状态：对于长时间运行的生成任务，监控异步任务状态。

generate_image

使用ModelScope异步API根据文本提示词生成图像。

参数说明

prompt（字符串，必填）：所需图像的文本描述。
model（字符串，可选，默认值：Qwen/Qwen-Image）：传递给API的模型名称。
size（字符串，可选，默认值：1024x1024）：图像分辨率大小，Qwen-Image支持范围：[64x64,1664x1664]。
output_filename（字符串，可选，默认值：result_image.jpg）：保存第一张输出图像的本地文件名。
output_dir（字符串，可选，默认值：./outputs）：保存图像的目录路径。

调用示例（MCP客户端发送的概念性JSON）

{
  "name": "generate_image",
  "arguments": {
    "prompt": "A golden cat playing in a garden",
    "size": "1024x1024",
    "output_filename": "cat.jpg",
    "output_dir": "./my_images"
  }
}

响应示例（返回给客户端的文本响应负载）

图片生成成功！
提示词: A golden cat playing in a garden
模型: Qwen/Qwen-Image
保存路径: /path/to/my_images/cat.jpg
输出目录: /path/to/my_images
文件名: cat.jpg
图片URL: https://.../generated_image.jpg

注意事项

仅使用第一个图像URL（如果返回多个）。
如果任务失败或超时，将收到详细的错误信息。
当前不返回base64数据（后续计划支持）。

🔧 技术细节

内部流程

使用请求头 X-ModelScope-Async-Mode: true 提交异步生成请求。
每5秒轮询一次任务端点 /v1/tasks/{task_id}（最多120次，约2分钟）。
任务成功后，下载第一张图像并使用Pillow（PIL）保存。
将文本元数据返回给MCP客户端。
若出现错误或超时，提供清晰的错误信息。

📚 详细文档

路线图

以下是计划中的增强功能（尚未在server.py中实现）：

可选的base64数据返回。
负提示词和引导参数支持。
可通过参数调整轮询间隔和超时时间。
多图像输出选择。
流式进度通知。

开发

# 安装所有依赖（包括开发依赖）
uv sync --dev

# 直接运行服务器模块
uv run python -m modelscope_image_mcp.server

# 或者通过uvx使用本地源代码运行
uvx --from . modelscope-image-mcp

# 带环境变量运行
MODELSCOPE_SDK_TOKEN=your_token_here uv run python -m modelscope_image_mcp.server

# 格式化代码（如果配置了ruff）
uv run ruff format .

# 代码检查（如果配置了ruff）
uv run ruff check . --fix

项目结构

modelscope-image-mcp/
├── src/modelscope_image_mcp/
│   ├── __init__.py
│   └── server.py          # 主MCP服务器实现
├── pyproject.toml         # 项目配置和依赖
├── uv.lock               # 用于可重复构建的锁文件
├── README.md             # 本文件
└── README-zh.md         # 中文文档

故障排除

| 问题症状 | 可能原因 | 解决方法 | |---------|----------------|--------| | ValueError: 需要设置 MODELSCOPE_SDK_TOKEN 环境变量 | 缺少令牌 | 导出/设置环境变量，然后重启 | | 图片生成超时 | 模型处理速度慢 | 重新运行；后续将支持更长的超时参数 | | 网络相关 httpx.TimeoutException | 网络连接问题 | 检查网络并重试 | | PIL cannot identify image file | 接收到无效的图像数据 | 尝试不同的提示词或模型 | | Permission denied when saving | 输出目录权限问题 | 检查写入权限或更改输出目录 | | No such file or directory | 输出目录不存在 | 服务器将自动创建该目录，或指定已存在的路径 |

变更日志

1.0.1

增加了对size参数的支持，可自定义图像分辨率。
改进了Qwen-Image模型的图像生成，支持分辨率范围为[64x64,1664x1664]。
增强了文档，添加了size参数的使用示例。

1.0.0

重大更新，改进了异步处理和输出目录支持。
增加了可配置的输出目录参数。
增强了错误处理和日志记录。
更新了依赖项，使用httpx以获得更好的异步支持。
修复了初始版本中的notification_options 错误。

0.1.0

初始最小化实现，支持异步轮询和本地图像保存。
修复了一个错误：之前notification_options为None导致的AttributeError。

📄 许可证

本项目采用MIT许可证。

贡献说明

欢迎提交PR和提出问题。请详细描述任何故障的复现步骤。

免责声明

这是一个非官方的集成示例。使用时请自行承担风险，并遵守ModelScope的服务条款。