Content
image-mcp
An MCP-based image generation server, compatible with the OpenAI Images API. It provides a `create-image` tool that generates images based on prompts and supports two output methods:
- Directly save to disk
- Return as base64 to the MCP client
Official References:
- MCP TypeScript SDK Official Documentation: <https://ts.sdk.modelcontextprotocol.io/>
- MCP Official SDK Page: <https://modelcontextprotocol.io/docs/sdk>
- OpenAI Image Generation Official Documentation: <https://developers.openai.com/api/docs/guides/image-generation>
## Features
- Provides `create-image` MCP tool
- Supports `prompt` image generation
- Supports passing `model`, default value is `gpt-image-2`
- Supports passing default size ratio options: `1:1`, `9:16`, `16:9`
- Supports passing `n` to specify the number of generated images
- Supports output to disk `file`
- Supports returning as inline `base64`
- Supports configuring upstream image service `baseURL`
- Supports custom request `headers`
- Supports configuring `API_KEY`
- Supports configuring default image generation model
- Runs based on `stdio`, convenient for connecting to MCP clients like Claude Desktop, Cursor, Cherry Studio, etc.
## Project Structure
```text
.
├── .env.example
├── package.json
├── src
│ ├── config.ts
│ ├── image-api.ts
│ └── index.ts
└── README.md
```
## Environment Requirements
- Node.js `>= 18.17`
- An image generation service compatible with OpenAI Images API
## Installation
```bash
npm install
```
## Configuration
The service reads upstream image interface configuration through environment variables.
The service will automatically load the `.env` file in the current working directory when started, so you can directly write the configuration into `.env` without manually `export` during local development.
### Required or Common Configurations
| Variable Name | Description | Default Value |
| ------------------------- | ------------------------------------------------ | --------------------------- |
| `IMAGE_API_BASE_URL` | Upstream image service address, usually `https://xxx/v1` | `https://api.openai.com/v1` |
| `IMAGE_API_KEY` | Upstream image service API Key | None |
| `IMAGE_MODEL` | Default image generation model name | `gpt-image-2` |
| `IMAGE_API_HEADERS` | Additional request headers, in JSON string format | `{}` |
| `IMAGE_OUTPUT_DIR` | Default output directory | `generated-images` |
| `IMAGE_REQUEST_TIMEOUT_MS`| Request timeout time, in milliseconds | `300000` |
### Compatible Aliases
For easy migration, the following aliases are also supported:
- `OPENAI_BASE_URL`
- `OPENAI_API_KEY`
- `OPENAI_IMAGE_MODEL`
- `OPENAI_MODEL`
### Configuration Example
```bash
export IMAGE_API_BASE_URL="https://api.openai.com/v1"
export IMAGE_API_KEY="sk-xxxxx"
export IMAGE_MODEL="gpt-image-2"
export IMAGE_API_HEADERS='{"X-Request-Source":"image-mcp"}'
export IMAGE_OUTPUT_DIR="./generated-images"
export IMAGE_REQUEST_TIMEOUT_MS="300000"
```
You can also refer to the [.env.example](/Users/xiaobc/work/projects/xiaobc/image-mcp/.env.example) in the repository.
## Startup Methods
### Development Mode
```bash
npm run dev
```
### Build and Run
```bash
npm run build
npm start
```
### MCP Debugging
```bash
npx @modelcontextprotocol/inspector node dist/index.js
```
## MCP Tool Description
### Tool Name
`create-image`
### Input Parameters
| Parameter Name | Type | Required | Description |
| --------------- | --------------------------- | -------- | ------------------------------------------------------------- |
| `prompt` | `string` | Yes | Image generation prompt |
| `model` | `string` | No | Model name used for this call, not passing uses `IMAGE_MODEL` |
| `size` | `"1:1" \| "9:16" \| "16:9"` | No | Default size ratio options, default `1:1` |
| `customSize` | `string` | No | Custom original pixel size, e.g., `1024x1024`. Passing will override `size` |
| `n` | `number` | No | Number of images to generate, default `1` |
| `output` | `"file" \| "base64"` | No | Output mode, default `file` |
| `outputDir` | `string` | No | Output directory when `output=file` |
| `fileNamePrefix`| `string` | No | File name prefix when `output=file` |
### Output Results
The size will be passed to the upstream image interface according to the following default mapping:
| Ratio Option | Actual Size |
| ------------ | -------------- |
| `1:1` | `1024x1024` |
| `9:16` | `1024x1792` |
| `16:9` | `1792x1024` |
#### When `output=file`
The return structure will contain:
- `mode`
- `model`
- `size`
- `count`
- `createdAt`
- `files`
Where `files` is like:
```json
[
{
"path": "/absolute/path/generated-images/cute-cat-1.png",
"mimeType": "image/png"
}
]
```
#### When `output=base64`
The return structure will contain:
- `mode`
- `model`
- `size`
- `count`
- `createdAt`
- `images`
Where `images` is like:
```json
[
{
"base64": "iVBORw0KGgoAAAANSUhEUgAA...",
"mimeType": "image/png",
"revisedPrompt": "..."
}
]
```
The original base64 is placed in `structuredContent.images[].base64` for easy client-side use.
## Usage Examples
### Example 1: Generate Image and Save to Disk
```json
{
"prompt": "a cinematic close-up of a silver robot reading a newspaper in a rainy cafe",
"model": "gpt-image-2",
"size": "1:1",
"n": 1,
"output": "file",
"outputDir": "./generated-images",
"fileNamePrefix": "robot-cafe"
}
```
### Example 2: Generate Image and Return base64
```json
{
"prompt": "minimalist poster design for a mountain travel campaign",
"size": "9:16",
"n": 2,
"output": "base64"
}
```
## MCP Client Access
The following is a general `stdio` configuration example. You can make adjustments according to your MCP client format.
### Method 1: Run in Development Mode
```json
{
"mcpServers": {
"image-mcp": {
"command": "npm",
"args": ["run", "dev"],
"cwd": "/Users/xiaobc/work/projects/xiaobc/image-mcp",
"env": {
"IMAGE_API_BASE_URL": "https://api.openai.com/v1",
"IMAGE_API_KEY": "sk-xxxxx",
"IMAGE_MODEL": "gpt-image-2",
"IMAGE_API_HEADERS": "{\"X-Request-Source\":\"image-mcp\"}",
"IMAGE_OUTPUT_DIR": "./generated-images"
}
}
}
}
```
### Method 2: Run after Building
```json
{
"mcpServers": {
"image-mcp": {
"command": "node",
"args": ["dist/index.js"],
"cwd": "/Users/xiaobc/work/projects/xiaobc/image-mcp",
"env": {
"IMAGE_API_BASE_URL": "https://api.openai.com/v1",
"IMAGE_API_KEY": "sk-xxxxx",
"IMAGE_MODEL": "gpt-image-2"
}
}
}
}
```
## Implementation Description
- The service exposes MCP capabilities through `stdio`
- The tool calls the upstream interface address: `{IMAGE_API_BASE_URL}/images/generations`
- `size` provides `1:1 / 9:16 / 16:9` three ratio options by default
- The default ratio will be mapped to `1024x1024 / 1024x1792 / 1792x1024` respectively
- If `customSize` is passed, it will be used first
- The default `Authorization: Bearer <IMAGE_API_KEY>` will be sent
- If `IMAGE_API_HEADERS` is configured, these custom request headers will be sent together
- Custom request headers will override default headers with the same name, making it easy to access non-standard compatible services
- If the upstream returns an image URL, the service will automatically download and convert it to base64, then decide whether to save to disk or return to the client
- If the upstream is slow, you can increase the timeout by `IMAGE_REQUEST_TIMEOUT_MS`
## Frequently Asked Questions
### 1. Why does authentication still fail even if the API Key is configured?
Possible reasons:
- The upstream service requires an authentication header that is not `Authorization`
- Your gateway requires additional custom headers
In this scenario, you can override or supplement the request headers through `IMAGE_API_HEADERS`, for example:
```bash
export IMAGE_API_HEADERS='{"Authorization":"Bearer xxx","X-App-Id":"demo"}'
```
### 2. Why is the returned format not png?
The service will automatically judge the extension based on the MIME type or image content returned by the upstream, and may save it as:
- `.png`
- `.jpg`
- `.webp`
### 3. What if the base64 is too large?
If the image is large or the number of generated images is large, it is recommended to use `output=file`, which is more suitable for daily workflows and can also avoid the MCP response body from being too large.
## Future Expansion Directions
- Add image editing `edit-image`
- Add reference image input
- Add output format, quality, background transparency, and other advanced parameters
- Add HTTP Streamable MCP transmission method
