Modelscope Image MCP

🚀 ModelScope Image MCP Server

このサーバーは、ModelScopeの画像生成APIを介して画像を生成するためのMCP（Model Context Protocol）サーバーです。AIアシスタントとのシームレスな統合を提供し、自然言語プロンプトを通じて画像を作成することができ、強力な非同期処理とローカルファイル管理機能を備えています。

⚠️ 重要な注意

このREADMEの初期ドラフトでは、base64データの返却、ネガティブプロンプト、追加パラメータなどの機能が記載されていました。現在公開されているコード（src/modelscope_image_mcp/server.py を参照）では、最小限の機能セットが実装されています：非同期タスクを送信し、生成された画像をローカルに保存する1つのツール generate_image です。計画中または今後追加予定の機能は、以下のロードマップに記載されています。

🚀 クイックスタート

環境変数の設定

サーバーは以下の環境変数から認証情報を読み取ります。

MODELSCOPE_SDK_TOKEN

この環境変数が設定されていない場合、サーバーはエラーを発生させます。トークンは こちら から取得できます。

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

インストールとMCPクライアントの設定

uvx を使用することで、事前に手動でインストールすることなく、MCP互換クライアント（例: Claude Desktop）にサーバーを直接登録できます。

オプション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

正常に実行されると、タスクの送信とポーリングを示すログが表示されます。

✨ 主な機能

• ModelScopeの非同期タスクAPIを使用した非同期画像生成
• 定期的なタスクステータスのポーリング（5秒ごと、最大2分間）
• 最初に生成された画像をローカルファイルに保存
• タスクステータスと画像URLをMCPクライアントに返す
• 強力なエラーハンドリングとタイムアウトメッセージング
• uvx を使用した簡単な1コマンドでの起動

💻 使用例

基本的な使用法

{
  "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 (string, required): 希望する画像のテキスト説明
• model (string, optional, default: Qwen/Qwen-Image): APIに渡されるモデル名
• size (string, optional, default: 1024x1024): 画像の解像度サイズ、Qwen-Imageは [64x64,1664x1664] をサポートしています。
• output_filename (string, optional, default: result_image.jpg): 最初の出力画像を保存するローカルファイル名
• output_dir (string, optional, default: ./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. タスクエンドポイント /v1/tasks/{task_id} を5秒ごとにポーリング（最大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

• 非同期ポーリングとローカル画像保存を備えた初期の最小限の実装
• バグ修正: 以前はNoneだった notification_options がAttributeErrorを引き起こす問題を修正

📄 ライセンス

MIT License

コントリビューション

PRとイシューは大歓迎です。エラーが発生した場合は、再現手順を記述してください。

免責事項

これは非公式の統合例です。自己責任で使用してください。ModelScopeのサービス利用規約に従ってください。