| Name | modelscope-image-mcp JSON |
| Version |
1.0.2
JSON |
| download |
| home_page | None |
| Summary | MCP Server for ModelScope Qwen-Image text-to-image generation |
| upload_time | 2025-09-12 06:21:46 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.10 |
| license | MIT License
Copyright (c) 2025 zym9863
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE. |
| keywords |
ai
generation
image
mcp
modelscope
qwen
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# ModelScope Image MCP Server
English | [中文](README-zh.md)
An MCP (Model Context Protocol) server for generating images via the ModelScope image generation API. This server provides seamless integration with AI assistants, enabling them to create images through natural language prompts with robust async processing and local file management.
> IMPORTANT: Earlier drafts of this README mentioned features like returning base64 data, negative prompts, and additional parameters. The current released code (see `src/modelscope_image_mcp/server.py`) implements a focused minimal feature set: one tool `generate_image` that submits an async task and saves the resulting image locally. Planned / upcoming features are listed in the roadmap below.
## Current Features
- Asynchronous image generation using ModelScope async task API
- Periodic task status polling (every 5 seconds, up to 2 minutes)
- Saves the first generated image to a local file
- Returns task status and image URL to the MCP client
- Robust error handling + timeout messaging
- Simple one-command start with `uvx`
## Environment Variable
The server reads your credential from:
```
MODELSCOPE_SDK_TOKEN
```
If it is missing, the server will raise an error. Obtain a token from: https://modelscope.cn/my/myaccesstoken
### Set on 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
```
## Installation & MCP Client Configuration
You can register the server directly in an MCP-compatible client (e.g. Claude Desktop) without a prior manual install thanks to `uvx`.
### Option 1: PyPI (Recommended once published)
```jsonc
{
"mcpServers": {
"modelscope-image": {
"command": "uvx",
"args": ["modelscope-image-mcp"],
"env": {
"MODELSCOPE_SDK_TOKEN": "your_token_here"
}
}
}
}
```
### Option 2: Direct from GitHub
```jsonc
{
"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"
}
}
}
}
```
### Option 3: Local Development Checkout
```bash
git clone https://github.com/zym9863/modelscope-image-mcp.git
cd modelscope-image-mcp
uv sync
```
Then configure MCP client entry using:
```jsonc
{
"mcpServers": {
"modelscope-image": {
"command": "uvx",
"args": ["--from", ".", "modelscope-image-mcp"],
"env": { "MODELSCOPE_SDK_TOKEN": "your_token_here" }
}
}
}
```
## Quick Local Smoke Test
```bash
# Run directly (local checkout)
uvx --from . modelscope-image-mcp
```
When running successfully you should see log lines showing task submission and polling.
```
## Usage Examples
### Basic Image Generation
```jsonc
{
"name": "generate_image",
"arguments": {
"prompt": "A serene mountain landscape at sunset"
}
}
```
### Advanced Configuration
```jsonc
{
"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"
}
}
```
### Creative Prompts
- **Art Style**: "in the style of Van Gogh", "watercolor painting", "digital art"
- **Composition**: "close-up portrait", "wide-angle landscape", "bird's eye view"
- **Lighting**: "dramatic lighting", "golden hour", "studio lighting"
- **Mood**: "mysterious atmosphere", "vibrant colors", "minimalist design"
### Best Practices
1. **Be Specific**: Detailed prompts produce better results than vague ones
2. **Use References**: Mention specific art styles, artists, or time periods
3. **Experiment**: Try variations of your prompt to find the best result
4. **Organize Outputs**: Use descriptive filenames and organized directories
5. **Check Status**: Monitor the async task status for long-running generations
### generate_image
Creates an image from a text prompt using the ModelScope async API.
Parameters:
- prompt (string, required): The text description of the desired image
- model (string, optional, default: Qwen/Qwen-Image): Model name passed to API
- size (string, optional, default: 1024x1024): Image resolution size, Qwen-Image supports: [64x64,1664x1664]
- output_filename (string, optional, default: result_image.jpg): Local filename to save the first output image
- output_dir (string, optional, default: ./outputs): Directory path where the image will be saved
Sample invocation (conceptual JSON sent by MCP client):
```jsonc
{
"name": "generate_image",
"arguments": {
"prompt": "A golden cat playing in a garden",
"size": "1024x1024",
"output_filename": "cat.jpg",
"output_dir": "./my_images"
}
}
```
Sample textual response payload (returned to the client):
```
图片生成成功！
提示词: 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
```
Notes:
- Only the first image URL is used (if multiple are ever returned)
- If the task fails or times out you receive a descriptive message
- No base64 data is currently returned (roadmap item)
## Internal Flow
1. Submit async generation request with header `X-ModelScope-Async-Mode: true`
2. Poll task endpoint `/v1/tasks/{task_id}` every 5 seconds (max 120 attempts ~= 2 minutes)
3. On SUCCEED download first image and save via Pillow (PIL)
4. Return textual metadata to MCP client
5. Provide clear error / timeout messages otherwise
## Roadmap
Planned enhancements (not yet implemented in `server.py`):
- Optional base64 return data
- Negative prompt & guidance parameters
- Adjustable polling interval & timeout via arguments
- Multiple image outputs selection
- Streaming progress notifications
## Development
```bash
# Install all (including dev) dependencies
uv sync --dev
# Run server module directly
uv run python -m modelscope_image_mcp.server
# Or via uvx using local source
uvx --from . modelscope-image-mcp
# Run with environment variable
MODELSCOPE_SDK_TOKEN=your_token_here uv run python -m modelscope_image_mcp.server
# Format code (if ruff is configured)
uv run ruff format .
# Lint code (if ruff is configured)
uv run ruff check . --fix
```
### Project Structure
```
modelscope-image-mcp/
├── src/modelscope_image_mcp/
│ ├── __init__.py
│ └── server.py # Main MCP server implementation
├── pyproject.toml # Project configuration and dependencies
├── uv.lock # Lock file for reproducible builds
├── README.md # This file
└── README-zh.md # Chinese documentation
```
## Troubleshooting
| Symptom | Possible Cause | Action |
|---------|----------------|--------|
| ValueError: 需要设置 MODELSCOPE_SDK_TOKEN 环境变量 | Token missing | Export / set environment variable then restart |
| 图片生成超时 | Slow model processing | Re-run; later we will expose longer timeout argument |
| 网络相关 httpx.TimeoutException | Connectivity issues | Check network / retry |
| PIL cannot identify image file | Invalid image data received | Try a different prompt or model |
| Permission denied when saving | Output directory permissions | Check write permissions or change output_dir |
| No such file or directory | Output directory doesn't exist | Server will create it automatically, or specify existing path |
## Changelog
### 1.0.1
- Added size parameter support for customizable image resolution
- Improved image generation with Qwen-Image model resolution range [64x64,1664x1664]
- Enhanced documentation with size parameter usage examples
### 1.0.0
- Major update with improved async handling and output directory support
- Added configurable output directory parameter
- Enhanced error handling and logging
- Updated dependencies to use httpx for better async support
- Fixed notification_options bug from initial release
### 0.1.0
- Initial minimal implementation with async polling & local image save
- Fixed bug: `notification_options` previously None causing AttributeError
## License
MIT License
## Contributing
PRs & issues welcome. Please describe reproduction steps for any failures.
## Disclaimer
This is an unofficial integration example. Use at your own risk; abide by ModelScope Terms of Service.
Raw data
{
"_id": null,
"home_page": null,
"name": "modelscope-image-mcp",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": "ai, generation, image, mcp, modelscope, qwen",
"author": null,
"author_email": "zym9863 <ym214413520@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/ef/4e/a70228508799b53d7786a792471d1f8e4834f96101cd79afe88d1bcd9d09/modelscope_image_mcp-1.0.2.tar.gz",
"platform": null,
"description": "# ModelScope Image MCP Server\n\nEnglish | [\u4e2d\u6587](README-zh.md)\n\nAn MCP (Model Context Protocol) server for generating images via the ModelScope image generation API. This server provides seamless integration with AI assistants, enabling them to create images through natural language prompts with robust async processing and local file management.\n\n> IMPORTANT: Earlier drafts of this README mentioned features like returning base64 data, negative prompts, and additional parameters. The current released code (see `src/modelscope_image_mcp/server.py`) implements a focused minimal feature set: one tool `generate_image` that submits an async task and saves the resulting image locally. Planned / upcoming features are listed in the roadmap below.\n\n## Current Features\n\n- Asynchronous image generation using ModelScope async task API\n- Periodic task status polling (every 5 seconds, up to 2 minutes)\n- Saves the first generated image to a local file\n- Returns task status and image URL to the MCP client\n- Robust error handling + timeout messaging\n- Simple one-command start with `uvx`\n\n## Environment Variable\n\nThe server reads your credential from:\n\n```\nMODELSCOPE_SDK_TOKEN\n```\n\nIf it is missing, the server will raise an error. Obtain a token from: https://modelscope.cn/my/myaccesstoken\n\n### Set on Windows (cmd):\n```\nset MODELSCOPE_SDK_TOKEN=your_token_here\n```\nPowerShell:\n```\n$env:MODELSCOPE_SDK_TOKEN=\"your_token_here\"\n```\nUnix/macOS bash/zsh:\n```\nexport MODELSCOPE_SDK_TOKEN=your_token_here\n```\n\n## Installation & MCP Client Configuration\n\nYou can register the server directly in an MCP-compatible client (e.g. Claude Desktop) without a prior manual install thanks to `uvx`.\n\n### Option 1: PyPI (Recommended once published)\n\n```jsonc\n{\n \"mcpServers\": {\n \"modelscope-image\": {\n \"command\": \"uvx\",\n \"args\": [\"modelscope-image-mcp\"],\n \"env\": {\n \"MODELSCOPE_SDK_TOKEN\": \"your_token_here\"\n }\n }\n }\n}\n```\n\n### Option 2: Direct from GitHub\n\n```jsonc\n{\n \"mcpServers\": {\n \"modelscope-image\": {\n \"command\": \"uvx\",\n \"args\": [\n \"--from\",\n \"git+https://github.com/zym9863/modelscope-image-mcp.git\",\n \"modelscope-image-mcp\"\n ],\n \"env\": {\n \"MODELSCOPE_SDK_TOKEN\": \"your_token_here\"\n }\n }\n }\n}\n```\n\n### Option 3: Local Development Checkout\n\n```bash\ngit clone https://github.com/zym9863/modelscope-image-mcp.git\ncd modelscope-image-mcp\nuv sync\n```\n\nThen configure MCP client entry using:\n\n```jsonc\n{\n \"mcpServers\": {\n \"modelscope-image\": {\n \"command\": \"uvx\",\n \"args\": [\"--from\", \".\", \"modelscope-image-mcp\"],\n \"env\": { \"MODELSCOPE_SDK_TOKEN\": \"your_token_here\" }\n }\n }\n}\n```\n\n## Quick Local Smoke Test\n\n```bash\n# Run directly (local checkout)\nuvx --from . modelscope-image-mcp\n```\n\nWhen running successfully you should see log lines showing task submission and polling.\n\n```\n\n## Usage Examples\n\n### Basic Image Generation\n\n```jsonc\n{\n \"name\": \"generate_image\",\n \"arguments\": {\n \"prompt\": \"A serene mountain landscape at sunset\"\n }\n}\n```\n\n### Advanced Configuration\n\n```jsonc\n{\n \"name\": \"generate_image\",\n \"arguments\": {\n \"prompt\": \"A futuristic city with flying cars, cyberpunk style\",\n \"model\": \"Qwen/Qwen-Image\",\n \"size\": \"1024x1024\",\n \"output_filename\": \"cyberpunk_city.png\",\n \"output_dir\": \"./generated_images\"\n }\n}\n```\n\n### Creative Prompts\n\n- **Art Style**: \"in the style of Van Gogh\", \"watercolor painting\", \"digital art\"\n- **Composition**: \"close-up portrait\", \"wide-angle landscape\", \"bird's eye view\"\n- **Lighting**: \"dramatic lighting\", \"golden hour\", \"studio lighting\"\n- **Mood**: \"mysterious atmosphere\", \"vibrant colors\", \"minimalist design\"\n\n### Best Practices\n\n1. **Be Specific**: Detailed prompts produce better results than vague ones\n2. **Use References**: Mention specific art styles, artists, or time periods\n3. **Experiment**: Try variations of your prompt to find the best result\n4. **Organize Outputs**: Use descriptive filenames and organized directories\n5. **Check Status**: Monitor the async task status for long-running generations\n\n### generate_image\n\nCreates an image from a text prompt using the ModelScope async API.\n\nParameters:\n- prompt (string, required): The text description of the desired image\n- model (string, optional, default: Qwen/Qwen-Image): Model name passed to API\n- size (string, optional, default: 1024x1024): Image resolution size, Qwen-Image supports: [64x64,1664x1664]\n- output_filename (string, optional, default: result_image.jpg): Local filename to save the first output image\n- output_dir (string, optional, default: ./outputs): Directory path where the image will be saved\n\nSample invocation (conceptual JSON sent by MCP client):\n\n```jsonc\n{\n \"name\": \"generate_image\",\n \"arguments\": {\n \"prompt\": \"A golden cat playing in a garden\",\n \"size\": \"1024x1024\",\n \"output_filename\": \"cat.jpg\",\n \"output_dir\": \"./my_images\"\n }\n}\n```\n\nSample textual response payload (returned to the client):\n\n```\n\u56fe\u7247\u751f\u6210\u6210\u529f\uff01\n\u63d0\u793a\u8bcd: A golden cat playing in a garden\n\u6a21\u578b: Qwen/Qwen-Image\n\u4fdd\u5b58\u8def\u5f84: /path/to/my_images/cat.jpg\n\u8f93\u51fa\u76ee\u5f55: /path/to/my_images\n\u6587\u4ef6\u540d: cat.jpg\n\u56fe\u7247URL: https://.../generated_image.jpg\n```\n\nNotes:\n- Only the first image URL is used (if multiple are ever returned)\n- If the task fails or times out you receive a descriptive message\n- No base64 data is currently returned (roadmap item)\n\n## Internal Flow\n\n1. Submit async generation request with header `X-ModelScope-Async-Mode: true`\n2. Poll task endpoint `/v1/tasks/{task_id}` every 5 seconds (max 120 attempts ~= 2 minutes)\n3. On SUCCEED download first image and save via Pillow (PIL)\n4. Return textual metadata to MCP client\n5. Provide clear error / timeout messages otherwise\n\n## Roadmap\n\nPlanned enhancements (not yet implemented in `server.py`):\n- Optional base64 return data\n- Negative prompt & guidance parameters\n- Adjustable polling interval & timeout via arguments\n- Multiple image outputs selection\n- Streaming progress notifications\n\n## Development\n\n```bash\n# Install all (including dev) dependencies\nuv sync --dev\n\n# Run server module directly\nuv run python -m modelscope_image_mcp.server\n\n# Or via uvx using local source\nuvx --from . modelscope-image-mcp\n\n# Run with environment variable\nMODELSCOPE_SDK_TOKEN=your_token_here uv run python -m modelscope_image_mcp.server\n\n# Format code (if ruff is configured)\nuv run ruff format .\n\n# Lint code (if ruff is configured)\nuv run ruff check . --fix\n```\n\n### Project Structure\n\n```\nmodelscope-image-mcp/\n\u251c\u2500\u2500 src/modelscope_image_mcp/\n\u2502 \u251c\u2500\u2500 __init__.py\n\u2502 \u2514\u2500\u2500 server.py # Main MCP server implementation\n\u251c\u2500\u2500 pyproject.toml # Project configuration and dependencies\n\u251c\u2500\u2500 uv.lock # Lock file for reproducible builds\n\u251c\u2500\u2500 README.md # This file\n\u2514\u2500\u2500 README-zh.md # Chinese documentation\n```\n\n## Troubleshooting\n\n| Symptom | Possible Cause | Action |\n|---------|----------------|--------|\n| ValueError: \u9700\u8981\u8bbe\u7f6e MODELSCOPE_SDK_TOKEN \u73af\u5883\u53d8\u91cf | Token missing | Export / set environment variable then restart |\n| \u56fe\u7247\u751f\u6210\u8d85\u65f6 | Slow model processing | Re-run; later we will expose longer timeout argument |\n| \u7f51\u7edc\u76f8\u5173 httpx.TimeoutException | Connectivity issues | Check network / retry |\n| PIL cannot identify image file | Invalid image data received | Try a different prompt or model |\n| Permission denied when saving | Output directory permissions | Check write permissions or change output_dir |\n| No such file or directory | Output directory doesn't exist | Server will create it automatically, or specify existing path |\n\n## Changelog\n\n### 1.0.1\n- Added size parameter support for customizable image resolution\n- Improved image generation with Qwen-Image model resolution range [64x64,1664x1664]\n- Enhanced documentation with size parameter usage examples\n\n### 1.0.0\n- Major update with improved async handling and output directory support\n- Added configurable output directory parameter\n- Enhanced error handling and logging\n- Updated dependencies to use httpx for better async support\n- Fixed notification_options bug from initial release\n\n### 0.1.0\n- Initial minimal implementation with async polling & local image save\n- Fixed bug: `notification_options` previously None causing AttributeError\n\n## License\n\nMIT License\n\n## Contributing\n\nPRs & issues welcome. Please describe reproduction steps for any failures.\n\n## Disclaimer\n\nThis is an unofficial integration example. Use at your own risk; abide by ModelScope Terms of Service.",
"bugtrack_url": null,
"license": "MIT License\n \n Copyright (c) 2025 zym9863\n \n Permission is hereby granted, free of charge, to any person obtaining a copy\n of this software and associated documentation files (the \"Software\"), to deal\n in the Software without restriction, including without limitation the rights\n to use, copy, modify, merge, publish, distribute, sublicense, and/or sell\n copies of the Software, and to permit persons to whom the Software is\n furnished to do so, subject to the following conditions:\n \n The above copyright notice and this permission notice shall be included in all\n copies or substantial portions of the Software.\n \n THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\n IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\n FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\n AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\n LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\n OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\n SOFTWARE.",
"summary": "MCP Server for ModelScope Qwen-Image text-to-image generation",
"version": "1.0.2",
"project_urls": {
"Bug Tracker": "https://github.com/zym9863/modelscope-image-mcp/issues",
"Homepage": "https://github.com/zym9863/modelscope-image-mcp",
"Repository": "https://github.com/zym9863/modelscope-image-mcp"
},
"split_keywords": [
"ai",
" generation",
" image",
" mcp",
" modelscope",
" qwen"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "c509176a7a6e786c3af92adddfe55ca00961e266b2631466452110ba9ebc1b21",
"md5": "c4ae0690f8f7e980ce0710fc5c9e51ef",
"sha256": "bc029da04a6f14134bc87ad99a47f600e09393973abca2f01ceca8c4a129052f"
},
"downloads": -1,
"filename": "modelscope_image_mcp-1.0.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "c4ae0690f8f7e980ce0710fc5c9e51ef",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 9970,
"upload_time": "2025-09-12T06:21:45",
"upload_time_iso_8601": "2025-09-12T06:21:45.228180Z",
"url": "https://files.pythonhosted.org/packages/c5/09/176a7a6e786c3af92adddfe55ca00961e266b2631466452110ba9ebc1b21/modelscope_image_mcp-1.0.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "ef4ea70228508799b53d7786a792471d1f8e4834f96101cd79afe88d1bcd9d09",
"md5": "56571331adb03e4a217fc5dacfe548e7",
"sha256": "7602db3744422905c8e9435fde7ad1977951e1de1d7a161efcd45aafcb074157"
},
"downloads": -1,
"filename": "modelscope_image_mcp-1.0.2.tar.gz",
"has_sig": false,
"md5_digest": "56571331adb03e4a217fc5dacfe548e7",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 58088,
"upload_time": "2025-09-12T06:21:46",
"upload_time_iso_8601": "2025-09-12T06:21:46.966961Z",
"url": "https://files.pythonhosted.org/packages/ef/4e/a70228508799b53d7786a792471d1f8e4834f96101cd79afe88d1bcd9d09/modelscope_image_mcp-1.0.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-09-12 06:21:46",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "zym9863",
"github_project": "modelscope-image-mcp",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "modelscope-image-mcp"
}
