Content
# image-gen-mcp
[English](README.en.md)
A picture generation and editing service based on **Model Context Protocol (MCP)**, which can be connected to Claude Cowork / Desktop / Code or any MCP-supported client.
The call is **non-blocking**: `generate_image` and `edit_image` return `task_id` immediately (long before the 60-second timeout), and the client then polls the result through `check_task` - even if the upstream image generation takes 3 minutes.
Compatible with any OpenAI-compatible image API, the main support modes are:
- `images`: `Images API`
- `responses`: `Responses API`
- `chat`: Compatible fallback mode, not preferred
---
## Sponsorship
The computing power used in this project is sponsored by **[Codox](https://www.codox.cc)**.
Codox is a platform that provides mainstream model computing power, supporting GPT (Codex), Claude Sonnet / Opus and other commonly used models, which can be directly connected to Codex CLI, Claude Code, Claude Desktop and other tools. ** preferential exchange rate: 1 yuan = 5 dollars**, welcome to experience.
---
## Tool List
| Tool | Description |
|------|------|
| `get_server_config` | View the current server configuration, including default output directory, backend, endpoint path, and sanitized API Key preview |
| `generate_image` | Submit a text-to-image task and return `task_id` immediately |
| `edit_image` | Submit an image editing task, supporting masked editing, unmasked editing, and up to 16 reference images, and return `task_id` immediately |
| `check_task` | Query the task status through `task_id`, and return the file path after completion |
| `list_task_history` | View the recent 50 task histories, which can be filtered by status |
| `list_generated_images` | List image files in the directory by glob |
### Asynchronous Process
```
generate_image(prompt="...")
→ { task_id: "abc123", status: "pending" }
check_task(task_id="abc123") ← Poll every 10-30 seconds
→ { status: "running" }
check_task(task_id="abc123")
→ { status: "done", saved_paths: ["C:/Users/<you>/Pictures/image-gen-mcp/img_xxx.png"], elapsed_seconds: 87.3 }
```
---
## Installation
### Prerequisites
- Python 3.10+
### Windows
```powershell
git clone https://github.com/xcdd/image-gen-mcp.git "$env:USERPROFILE\.claude\image_gen_mcp"
cd "$env:USERPROFILE\.claude\image_gen_mcp"
python -m venv .venv
.venv\Scripts\pip install -r requirements.txt
```
### Linux / macOS
```bash
git clone https://github.com/xcdd/image-gen-mcp.git ~/.local/share/image-gen-mcp
cd ~/.local/share/image-gen-mcp
python3 -m venv .venv
.venv/bin/pip install -r requirements.txt
```
---
## Register to MCP Client
### Claude Cowork / Desktop (Windows)
Configuration file: `C:\Users\<username>\AppData\Local\Claude-3p\claude_desktop_config.json`
```json
"image-gen": {
"command": "C:\\Users\\<username>\\.claude\\image_gen_mcp\\.venv\\Scripts\\python.exe",
"args": ["C:\\Users\\<username>\\.claude\\image_gen_mcp\\server.py"],
"env": {
"IMAGE_API_BASE_URL": "https://your-api-host",
"IMAGE_API_KEY": "sk-..."
}
}
```
### Claude Cowork / Desktop (macOS / Linux)
Configuration file: `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS)
```json
"image-gen": {
"command": "/home/<username>/.local/share/image-gen-mcp/.venv/bin/python",
"args": ["/home/<username>/.local/share/image-gen-mcp/server.py"],
"env": {
"IMAGE_API_BASE_URL": "https://your-api-host",
"IMAGE_API_KEY": "sk-..."
}
}
```
### Claude Code
Edit `~/.claude/mcp.json`:
```json
{
"mcpServers": {
"image-gen": {
"command": "/path/to/.venv/bin/python",
"args": ["/path/to/server.py"],
"env": {
"IMAGE_API_BASE_URL": "https://your-api-host",
"IMAGE_API_KEY": "sk-..."
}
}
}
}
```
Restart the client after configuration, and `image-gen` should appear in the MCP plugin list, containing 6 tools.
---
## Environment Variables
| Variable | Default Value | Description |
|------|--------|------|
| `IMAGE_API_BASE_URL` | **Required** | Upstream API root address, e.g., `https://www.codox.cc`. No trailing slash, the server will automatically append paths like `/v1/images/generations` |
| `IMAGE_API_KEY` | **Required** | Bearer Token |
| `IMAGE_API_BACKEND` | `images` | Backend type: `images` / `responses` / `chat`, see [Backend Description](#backend-description) |
| `IMAGE_OUTPUT_DIR` | `~/Pictures/image-gen-mcp` | Default output directory. Supports absolute paths, `~`, and environment variable expansion |
| `IMAGE_DEFAULT_MODEL` | `gpt-image-2` | Default model when the caller does not specify a model |
| `IMAGE_MAX_CONCURRENT` | `10` | Maximum concurrent requests (asyncio semaphore) |
| `IMAGE_REQUEST_TIMEOUT` | `1800` | Single request timeout in seconds, high-quality image generation may take more than 3 minutes |
| `IMAGE_RETRY_ATTEMPTS` | `3` | Retry attempts for 5xx / timeout / connection reset, with backoff intervals of 2s / 5s / 10s |
| `IMAGE_GEN_PATH` | `/v1/images/generations` | Image generation endpoint path (can be overridden) |
| `IMAGE_EDIT_PATH` | `/v1/images/edits` | Image editing endpoint path (can be overridden) |
| `IMAGE_CHAT_PATH` | `/v1/chat/completions` | Chat backend endpoint path |
| `IMAGE_RESPONSES_PATH` | `/v1/responses` | Responses backend endpoint path |
---
## Backend Description
| Backend | Endpoint | Applicable Scenarios |
|------|------|---------|
| `images` (default) | `POST /v1/images/generations` | Standard OpenAI image API, preferred |
| `responses` | `POST /v1/responses` | New Responses API (tool call), also main support mode |
| `chat` | `POST /v1/chat/completions` | Compatible fallback mode, some platforms encapsulate image generation through chat completions |
---
## Tool Parameter Details
### `get_server_config`
Recommended to call when AI or user is unsure about the current configuration:
```jsonc
{}
```
Returns:
- `default_output_dir`
- `backend`
- `configured_paths`
- `has_api_key`
- `api_key_preview`
- `warnings`
`api_key_preview` only shows the prefix and suffix, and the middle part is masked for human review.
---
### `generate_image`
```jsonc
{
"prompt": "Watercolor style cat sitting on the windowsill", // Required
"model": "gpt-image-2",
"size": "1024x1024", // 1024x1024 | 1536x1024 | 1024x1536 | 2048x2048
"n": 1, // 1-4
"quality": "auto", // auto | high | medium | low
"output_format": "png", // png | jpeg | webp
"output_compression": 80, // Only for jpeg/webp; ignored for png or transparent_output=true
"moderation": "auto", // auto | low
"negative_prompt": "Blurry, low quality",
"style_intensity": 50, // Style intensity 0-100
"background": "auto", // auto | transparent | white | opaque
"transparent_output": false, // Local post-processing for transparent background; forces PNG saving
"seed": 42,
"extra": {}, // Extra fields passed to API as-is
"output_dir": "C:/Users/<you>/Pictures/image-gen-mcp",
"filename_prefix": "cat_watercolor",
"backend": "images"
}
```
Returns immediately:
```json
{ "task_id": "3f9a...", "status": "pending", "message": "Task submitted. Use check_task to poll for completion." }
```
---
### `edit_image`
Supports all native editing modes of gpt-image-2:
- **Masked editing (Inpainting)**: Provide `mask_path` (PNG with Alpha channel), transparent areas are editing areas, and non-transparent areas remain unchanged
- **Unmasked editing**: Do not provide `mask_path`, describe the content to modify through `prompt`, and the model automatically locates the area
- **Multi-image synthesis / style transfer**: Provide up to 16 images through `image_paths`, the first image is the main image, and the rest are reference images
```jsonc
{
"prompt": "Change the background to a sunset beach, keep the main subject", // Required
"image_path": "C:/Users/User/Claude/photo.png", // Single image (or image_paths)
"image_paths": [ // Multiple images (up to 16)
"C:/Users/User/Claude/primary.png",
"C:/Users/User/Claude/style_ref.png"
],
"mask_path": "C:/Users/User/Claude/mask.png", // Optional, transparent area = editing range
"model": "gpt-image-2",
"size": "auto", // auto | 1024x1024 | 1536x1024 | 1024x1536
"n": 1, // Output variation count 1-10
"quality": "auto",
"output_format": "png",
"moderation": "auto", // auto | low
"output_compression": 85, // Compression ratio 0-100, only for jpeg/webp
"transparent_output": false, // Local post-processing for transparent background; forces PNG saving
"output_dir": "C:/Users/<you>/Pictures/image-gen-mcp",
"filename_prefix": "edited",
"backend": "images"
}
```
Returns `task_id` immediately, and use `check_task` to poll.
---
### `check_task`
```jsonc
{ "task_id": "3f9a..." }
```
Example return when completed:
```json
{
"task_id": "3f9a...",
"status": "done",
"saved_paths": ["C:/Users/User/Claude/cat_watercolor.png"],
"created_at": 1750123456.0,
"finished_at": 1750123543.3,
"elapsed_seconds": 87.3
}
```
---
### `list_task_history`
```jsonc
{ "status_filter": "done" } // all | done | error | pending | running
```
Returns the recent 50 task histories, sorted in descending order by completion time.
---
### `list_generated_images`
```jsonc
{ "directory": "C:/Users/<you>/Pictures/image-gen-mcp", "pattern": "img_*" }
```
---
## Usage Suggestions
1. If unsure about the current default directory, backend, or key, call `get_server_config` first.
2. `output_dir` can be omitted; if omitted, it defaults to `~/Pictures/image-gen-mcp`.
3. Transparent background `transparent_output=true` is **local post-processing**, not GPT-Image-2 native transparent channel.
4. `images` and `responses` are main support modes, and `chat` is only recommended for compatible scenarios.
5. **Set `filename_prefix`** to make output file names meaningful and easy to manage.
6. Vertical posters use `1024x1536`, horizontal posters use `1536x1024`, and square use `1024x1024`.
7. When text needs to appear in the image, using the corresponding language in the prompt is more effective.
8. `quality: "high"` has better results but takes about 2-3 times longer.
9. Multiple tasks can be submitted simultaneously, and the worker defaults to 10 concurrent tasks (controlled by `IMAGE_MAX_CONCURRENT`).
---
## Frequently Asked Questions
| Phenomenon | Possible Cause | Solution |
|------|---------|---------|
| MCP plugin shows disconnected | `command` or `args` path error | Confirm both are absolute paths, and `.venv` is created |
| `IMAGE_API_BASE_URL env var is not set` | Configuration JSON lacks `env` block | Add `env` block at the same level as `args`, or call `get_server_config` to view warnings |
| `Upstream error 401/403` | API Key invalid | Check `IMAGE_API_KEY` |
| `Upstream error 404` | Backend type or endpoint path error | Try other `IMAGE_API_BACKEND`, or override endpoint path variables |
| Task remains pending | Worker not started (abnormal) | Restart MCP client |
---
## Security Notes
- API Key is not logged or written to disk, only exists in process environment variables.
- `get_server_config` only returns sanitized `api_key_preview` for human review.
- `output_dir` is resolved to an absolute path and created automatically; relative paths are rejected.
- Image content in the output directory is not transmitted back to the upstream API.
---
## License
MIT
MCP Config
Below is the configuration for this MCP Server. You can copy it directly to Cursor or other MCP clients.
mcp.json
Connection Info
You Might Also Like
No recommendations available