# Image Gen MCP Server — 文生图能力代理 🎨

让 LLM 通过 MCP 调用 AI 模型生成图片。**只需一个 API Key，即可让任何 AI 客户端拥有图片生成能力。**

**每个部署者自行选择图片生成提供商和默认模型**，只需在部署时配置环境变量即可。

## 功能

| 工具 | 说明 |
|------|------|
| `generate_image` | 根据文字描述生成图片。传入 prompt + 可选参数，返回图片 URL |
| `list_image_models` | 查看当前提供商和推荐使用的模型列表 |

## 支持的图片生成提供商

| 提供商 | `IMAGE_PROVIDER` 值 | 特点 |
|--------|---------------------|------|
| **硅基流动** | `siliconflow` | 国内直接访问，免费额度，推荐中文用户 |
| **OpenAI** | `openai` | DALL-E 3，需国际网络 |
| **自定义接口** | `custom` | 任何 OpenAI 兼容接口（中转 API） |

## 一键运行（无需手动安装）

项目支持 **uvx** / **pip** 两种方式一键运行，无需手动克隆仓库。

| 方式 | 命令 | 前提条件 |
|------|------|----------|
| **uvx** 🏆 | `uvx --from git+https://github.com/DoctorPan/image-gen-mcp image-gen-mcp` | 安装 [uv](https://docs.astral.sh/uv/)（自动安装 Python 依赖） |
| **pip** | `pip install git+https://github.com/DoctorPan/image-gen-mcp && image-gen-mcp` | 安装 Python 3.10+ |

```bash
# uvx 运行（默认 stdio 模式，适用于本地 Reasonix 接入）
uvx --from git+https://github.com/DoctorPan/image-gen-mcp image-gen-mcp

# uvx 运行（SSE 模式，用于远程部署）
uvx --from git+https://github.com/DoctorPan/image-gen-mcp image-gen-mcp --transport sse --port 8000

# 需要先设置环境变量
set IMAGE_API_KEY=你的硅基流动APIKey
set IMAGE_PROVIDER=siliconflow
```

> 注意：uvx 会自动从 GitHub 拉取代码并安装 Python 依赖，首次运行可能需要几十秒。

## 在 Reasonix 中配置（推荐）

### 方式一：通过 uvx 一键运行（推荐）

无需克隆仓库、无需手动安装依赖，Reasonix 自动通过 uvx 拉取运行：

```json
{
  "mcpServers": {
    "image-gen-mcp": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/DoctorPan/image-gen-mcp", "image-gen-mcp"],
      "env": {
        "IMAGE_API_KEY": "你的硅基流动 API Key",
        "IMAGE_PROVIDER": "siliconflow",
        "DEFAULT_IMAGE_MODEL": "black-forest-labs/FLUX.1-dev"
      }
    }
  }
}
```

### 方式二：本地 Python 直接运行（已克隆项目）

```json
{
  "mcpServers": {
    "image-gen-mcp": {
      "command": "python",
      "args": ["C:\\path\\to\\image-gen-mcp\\server.py"],
      "env": {
        "IMAGE_API_KEY": "你的硅基流动 API Key",
        "IMAGE_PROVIDER": "siliconflow",
        "DEFAULT_IMAGE_MODEL": "black-forest-labs/FLUX.1-dev"
      }
    }
  }
}
```

### 方式三：远程 SSE URL（部署到魔搭后）

```json
{
  "mcpServers": {
    "image-gen-mcp": {
      "url": "https://mcp.api-inference.modelscope.net/xxxxx/mcp"
    }
  }
}
```

## 快速开始（本地开发）

```bash
# 1. 进入项目目录
cd image-gen-mcp

# 2. 安装依赖
pip install -r requirements.txt

# 3. 复制配置模板
copy .env.example .env

# 4. 编辑 .env，填入你的配置
#    IMAGE_API_KEY=sk-xxx
#    IMAGE_PROVIDER=siliconflow

# 5. 启动（默认 stdio 模式）
python server.py

# 或者本地测试 SSE 模式
python server.py --transport sse --port 8000
```

## 如何使用

### 示例：生成一张图片

```
generate_image(
  prompt="一只穿着西装的猫，坐在办公室的老板椅上，夕阳从窗外照进来，赛博朋克风格",
  model="black-forest-labs/FLUX.1-dev",
  size="1024x1024"
)
```

### 选择不同的提供商

在 `generate_image` 的 `model` 参数中传入不同的模型名称：

| 提供商 | 推荐模型 | 尺寸支持 |
|--------|----------|----------|
| 硅基流动 | `black-forest-labs/FLUX.1-dev` | 1024x1024、768x1344、864x1152、1344x768、1152x864 |
| 硅基流动 | `stabilityai/stable-diffusion-3-5-large` | 同上 |
| OpenAI | `dall-e-3` | 1024x1024、1792x1024、1024x1792 |
| OpenAI | `dall-e-2` | 256x256、512x512、1024x1024 |

## 部署到魔搭 Hosted（SSE 模式）🚀

魔搭社区提供 Hosted MCP 服务，可以将你的 MCP 服务器部署在魔搭云端，生成 SSE URL 供远程调用。

### 部署步骤

#### 第 1 步：将代码推送到 GitHub

```bash
cd image-gen-mcp
git init
git add .
git commit -m "初始提交"
git remote add origin https://github.com/DoctorPan/image-gen-mcp.git
git push -u origin main
```

#### 第 2 步：在魔搭提交 MCP 服务

1. 登录 https://modelscope.cn
2. 进入 **MCP 广场** → 点击 **提交 MCP 服务**
3. 填写以下信息：

| 字段 | 内容 |
|------|------|
| 服务名称 | `image-gen-mcp` |
| 中文名称 | 文生图能力代理 |
| 描述 | 让 LLM 通过 MCP 调用 AI 模型生成图片。支持硅基流动、OpenAI 等多个提供商。 |
| 源代码地址 | `https://github.com/DoctorPan/image-gen-mcp` |
| **启动命令** | `python server.py --transport sse --port 8000` |
| 传输方式 | SSE |

#### 第 3 步：部署 Hosted 服务

审核通过后，在 MCP 管理页面找到 `image-gen-mcp`，点击部署，选择 Hosted 部署类型，配置环境变量：

| 变量 | 必填 | 值 |
|------|------|-----|
| `IMAGE_API_KEY` | ✅ | 你的图片生成 API Key |
| `IMAGE_PROVIDER` | ❌ | `siliconflow`（默认） |
| `DEFAULT_IMAGE_MODEL` | ❌ | `black-forest-labs/FLUX.1-dev` |

部署成功后，魔搭会生成 SSE URL。

## 环境变量速查

| 环境变量 | 作用 | 示例值 |
|---------|------|--------|
| `IMAGE_API_KEY` | ⭐ 你的 API Key（必填） | `sk-xxx` |
| `IMAGE_PROVIDER` | 选择提供商 | `siliconflow` / `openai` / `custom` |
| `IMAGE_BASE_URL` | 自定义 API 地址 | `https://your-api.com/v1` |
| `DEFAULT_IMAGE_MODEL` | 调用的默认模型 | `black-forest-labs/FLUX.1-dev` |
| `DEFAULT_IMAGE_SIZE` | 默认图片尺寸 | `1024x1024` |
| `IMAGE_MCP_TRANSPORT` | 传输模式 | `stdio`（本地） / `sse`（远程） |
| `IMAGE_MCP_HOST` | SSE 监听地址 | `0.0.0.0` |
| `IMAGE_MCP_PORT` | SSE 监听端口 | `8000` |

## 命令行参数

```bash
python server.py --help

# 输出：
usage: server.py [-h] [--transport {stdio,sse}] [--host HOST] [--port PORT]

Image Gen MCP Server — 文生图能力代理

options:
  -h, --help            show this help message and exit
  --transport {stdio,sse}
                        传输模式: stdio (默认) / sse (远程部署)
  --host HOST           SSE 监听地址 (默认 0.0.0.0)
  --port PORT           SSE 监听端口 (默认 8000)
```

## 项目结构

```
image-gen-mcp/
├── pyproject.toml       # Python 项目配置，支持 uvx 一键运行
├── server.py            # MCP 服务器主代码
├── requirements.txt     # Python 依赖
├── .env.example         # 环境变量模板
├── .gitignore
└── README.md
```

## 许可证

MIT