ModelScope Image

You can run a ModelScope Image MCP Server that lets you generate images through natural language prompts. It processes requests asynchronously, saves the first generated image locally, and returns status and a direct image URL to your MCP client. This makes it easy to integrate image generation into your AI assistants and automation pipelines while keeping local file management simple.

How to use

Submit a prompt to generate an image. The server accepts an asynchronous task, polls for status every few seconds, and saves the first produced image to a local file. You’ll receive a concise status update and a URL to the generated image so you can display or store it in your workflow.

Use an MCP client to request image generation by providing a prompt and optional parameters like the model, size, and output filename. You can tailor prompts for style, composition, lighting, and mood to influence the generated image. Monitor the task status to know when the image is ready, and retrieve the image URL for use in your app.

How to install

Prerequisites you need before installation: a working Python environment and the MCP client tool you plan to use (e.g., uvx). You will also need a ModelScope SDK token for authentication.

Step 1. Install the MCP client tooling (uvx) if you don’t already have it.

Step 2. Obtain a ModelScope SDK token from the appropriate ModelScope account page and store it in your environment as MODELSCOPE_SDK_TOKEN.

Step 3. Register the MCP server in your MCP client configuration using one of the supported methods shown below.

Configuration and usage notes

Environment variable you must set: MODELSCOPE_SDK_TOKEN. This token authenticates with the ModelScope API to submit image generation tasks.

The server supports one primary tool named generate_image. It submits an async image generation task and saves the first image locally. It returns the task status and an image URL to the MCP client. If a task fails or times out, you receive a descriptive message.

Examples of how prompts can be enhanced include specifying art style, composition, lighting, and mood to guide the results.

MCP client configurations

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

Additional installation options

Option 2: Direct from GitHub for the MCP server package. This uses uvx to fetch the server from a Git repository and run it.

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

Local development workflow

If you are developing locally, clone the project, synchronize dependencies, and then configure your MCP client to point at the local source.

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

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

Quick local smoke test

Run the MCP server locally and ensure you see task submission and polling logs indicating the asynchronous flow.

Troubleshooting

If you encounter a missing token error, ensure MODELSCOPE_SDK_TOKEN is set in your environment and restart the server.

If image generation times out or fails, retry the task or adjust your prompt and model parameters to improve performance.

Examples and best practices

Be explicit in prompts for better results. Combine descriptive language about art style, composition, lighting, and mood to guide the image generation.

Available tools

generate_image

Creates an image from a text prompt using the ModelScope async API. Submits an async task, saves the first output image locally, and returns task status plus the image URL.