# ModelScope Image Generation MCP Server

一个用于魔搭社区（ModelScope）文生图服务的 MCP（Model Context Protocol）服务器，使用 Qwen/Qwen-Image 模型，支持在 Claude Desktop 等 MCP 客户端中使用。

## 功能特性

- 🎨 使用魔搭社区的 Qwen/Qwen-Image 模型生成图片
- 🔄 同步生图体验：调用工具后自动等待生成完成
- ⚙️ 完整参数支持：正向/负向提示词、分辨率、种子、采样步数、引导系数等
- 📦 支持 npx 一键安装和运行

## 安装

### 方式 1: 使用 npx（推荐）

无需安装，直接在 Claude Desktop 配置中使用：

```json
{
  "mcpServers": {
    "modelscope-image": {
      "command": "npx",
      "args": ["-y", "mcp-modelscope-image"],
      "env": {
        "MODELSCOPE_API_KEY": "your-api-key-here"
      }
    }
  }
}
```

### 方式 2: 全局安装

```bash
npm install -g mcp-modelscope-image
```

配置示例：

```json
{
  "mcpServers": {
    "modelscope-image": {
      "command": "mcp-modelscope-image",
      "env": {
        "MODELSCOPE_API_KEY": "your-api-key-here"
      }
    }
  }
}
```

### 方式 3: 本地开发

```bash
# 克隆或下载项目
cd mcp-local-modelscope-image

# 安装依赖
npm install

# 构建项目
npm run build
```

Claude Desktop 配置：

```json
{
  "mcpServers": {
    "modelscope-image": {
      "command": "node",
      "args": ["E:\\workspace\\jasion\\jq-mcp\\mcp-local-modelscope-image\\dist\\index.js"],
      "env": {
        "MODELSCOPE_API_KEY": "your-api-key-here"
      }
    }
  }
}
```

## 获取 API Key

1. 访问 [魔搭社区](https://www.modelscope.cn/)
2. 登录账号
3. 进入个人中心获取 API Token (MODELSCOPE_SDK_TOKEN)
4. 将 Token 配置为环境变量 `MODELSCOPE_API_KEY`

## 使用示例

在 Claude Desktop 中，你可以直接使用自然语言调用生图功能：

### 基础用法

```
请生成一张图片：一只金色的猫咪在阳光下玩耍
```

### 高级用法（指定详细参数）

```
生成图片：
- 提示词：A mysterious girl walking down the corridor, cinematic lighting, highly detailed
- 负向提示词：lowres, bad anatomy, text, watermark
- 分辨率：1024x1024
- 采样步数：30
- 引导系数：7.5
- 随机种子：12345
```

## 支持的参数

本服务使用 **Qwen/Qwen-Image** 模型，支持以下参数：

- **prompt** (必需): 正向提示词（建议使用英文）
  - 最大长度：2000 字符

- **negative_prompt** (可选): 负向提示词
  - 最大长度：2000 字符

- **size** (可选): 图片分辨率
  - 范围：[64x64, 1664x1664]
  - 默认：1024x1024

- **seed** (可选): 随机种子，用于可重复生成
  - 范围：[0, 2^31-1]

- **steps** (可选): 采样步数
  - 范围：[1, 100]

- **guidance** (可选): 提示词引导系数
  - 范围：[1.5, 20]

- **image_url** (可选): 待编辑图片的 URL（用于图片编辑模式）
  - 要求：公网可访问

## 配置文件位置

### Windows
```
%APPDATA%\Claude\claude_desktop_config.json
```

### macOS
```
~/Library/Application Support/Claude/claude_desktop_config.json
```

### Linux
```
~/.config/Claude/claude_desktop_config.json
```

## 开发

```bash
# 安装依赖
npm install

# 开发模式（监听文件变化）
npm run watch

# 构建
npm run build
```

## 故障排除

### 提示 API Key 未设置
确保在 Claude Desktop 配置文件中正确设置了 `MODELSCOPE_API_KEY` 环境变量。

### 生成失败
- 检查模型 ID 是否正确
- 检查提示词长度是否超过 2000 字符
- 检查参数值是否在允许范围内
- 查看 Claude Desktop 的开发者工具控制台获取详细错误信息

### npx 命令找不到
确保已安装 Node.js 18 或更高版本。

## 许可证

MIT

## 相关链接

- [魔搭社区](https://www.modelscope.cn/)
- [Model Context Protocol](https://modelcontextprotocol.io/)
- [Claude Desktop](https://claude.ai/download)