Metadata-Version: 2.4
Name: ms-image-gen-mcp
Version: 1.2.1
Summary: ModelScope Image Generator
Requires-Python: >=3.12
Requires-Dist: build>=1.2.2.post1
Requires-Dist: mcp[cli]>=1.11.0
Requires-Dist: requests>=2.32.3
Requires-Dist: twine>=6.1.0
Description-Content-Type: text/markdown

# ModelScope Image Generation MCP

A powerful Model Context Protocol (MCP) server that integrates with ModelScope's image generation capabilities, enabling seamless AI image creation and model discovery through chat interfaces.
## Features

- 🔍 **Model Discovery**: Search and explore models on ModelScope using keywords with advanced filtering options
- 🎨 **Text-to-Image**: Generate high-quality images from text descriptions using state-of-the-art models
- 🖼️ **Image-to-Image**: Transform existing images based on text prompts for creative editing
- 📊 **Model Analytics**: Sort models by popularity, download count, or modification date
- 🚀 **Easy Integration**: Seamless integration with MCP-compatible chat clients

## Available Tools

### Model Search Tool
🔍 **`search_models`** - Search and discover models on ModelScope

| Parameter | Type | Description | Example |
|-----------|------|-------------|---------|
| `query` | string | Search keywords | `"Flux"`, `"SDXL"`, `""` |
| `task` | string | Filter by task type (optional) | `"text-to-image"` |
| `libraries` | string | Filter by library type (optional) | `"LoRA"` |
| `sort` | string | Sort order (optional)  | `"DownloadsCount"`, `"StarsCount"`, `"GmtModified"` |
| `limit` | integer | Number of results (1-30) (optional) | `10` |

### Image Generation Tools

🎨 **`generate_image_url_from_text`** - Create images from text descriptions

| Parameter | Type | Description | Default |
|-----------|------|-------------|---------|
| `description` | string | Text prompt for image generation | Required |
| `model` | string | Default Model ID to use | `"Qwen/Qwen-Image"` |

✍️ **`generate_image_url_from_text_and_image_url`** - Transform existing images

| Parameter | Type | Description | Default |
|-----------|------|-------------|---------|
| `description` | string | Text prompt for image transformation | Required |
| `image_url` | string | URL of input image | Required |
| `model` | string | Default Model ID to use | `"black-forest-labs/FLUX.1-Kontext-dev"` |

### Popular Models Available

- **Text-to-Image**: `Qwen/Qwen-Image` (Default)
- **Image-to-Image**: `black-forest-labs/FLUX.1-Kontext-dev` (Default)  
- **And 10000+ more models** available through ModelScope platform!


## Configuration

### Step 1: Obtain API Key

Obtain your API key from [ModelScope API Key](https://www.modelscope.cn/my/myaccesstoken) for API access.

### Step 2: Configure MCP Client

Add the following configuration to your MCP client (e.g., Cherry Studio, Claude Desktop):

```json
{
  "modelscope-image-gen-mcp": {
    "command": "uvx",
    "args": ["ms_image_gen_mcp@latest"],
    "env": {
      "MODELSCOPE_API_KEY": "YOUR_MODELSCOPE_API_KEY"
    }
  }
}
```

## Development
### Prerequisites

- **Python 3.11+**: Required for running the MCP server
- **ModelScope API Key**: Obtain from [ModelScope](https://www.modelscope.cn/my/myaccesstoken) for API access
- **Node.js** (optional): Required for MCP Inspector debugging
    
### Installation

Install the package via pip:

```bash
pip install ms-image-gen-mcp
```


### Debugging with MCP Inspector

For development and debugging, use the MCP Inspector:

```bash
npx @modelcontextprotocol/inspector -e MODELSCOPE_API_KEY=YOUR_MODELSCOPE_API_KEY python -m ms_image_gen_mcp
```


## Version History

| Version | Changes |
|---------|---------|
| **1.2.0** | Convert to async API |
| **1.1.0** | Add model search and image-to-image generation |
| **1.0.0** | Initial release with text-to-image generation |