Modelscope Image MCP

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

使用建議

1. 明確描述：詳細的提示詞比模糊的提示詞能生成更好的圖像效果。
2. 參考借鑑：提及特定的藝術風格、藝術家或時期。
3. 大膽嘗試：嘗試不同的提示詞變體，以找到最佳結果。
4. 整理輸出：使用具有描述性的文件名和有組織的目錄。
5. 關注狀態：對於長時間運行的生成任務，監控異步任務狀態。

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數據（後續計劃支持）。

🔧 技術細節

內部流程

1. 使用請求頭 X-ModelScope-Async-Mode: true 提交異步生成請求。
2. 每5秒輪詢一次任務端點 /v1/tasks/{task_id}（最多120次，約2分鐘）。
3. 任務成功後，下載第一張圖像並使用Pillow（PIL）保存。
4. 將文本元數據返回給MCP客戶端。
5. 若出現錯誤或超時，提供清晰的錯誤信息。

📚 詳細文檔

路線圖

以下是計劃中的增強功能（尚未在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         # 中文文檔

故障排除

變更日誌

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的服務條款。