MCP OpenAI Image Generation Server

🚀 零安装配置！ 直接在MCP客户端中使用，无需任何预安装步骤

{
  "mcpServers": {
    "imagegen-mcp": {
      "command": "npx",
      "args": ["@lupinlin1/imagegen-mcp", "--models", "dall-e-3"],
      "env": { "OPENAI_API_KEY": "your_api_key" }
    }
  }
}

This project provides a server implementation based on the Model Context Protocol (MCP) that acts as a wrapper around OpenAI's Image Generation and Editing APIs (see OpenAI documentation).

Features

Exposes OpenAI image generation capabilities through MCP tools.
Supports text-to-image generation using models like DALL-E 2, DALL-E 3, and gpt-image-1 (if available/enabled).
Supports image-to-image editing using DALL-E 2 and gpt-image-1 (if available/enabled).
Configurable via environment variables and command-line arguments.
Handles various parameters like size, quality, style, format, etc.
Saves generated/edited images to temporary files and returns the path along with the base64 data.

Here's an example of generating an image directly in Cursor using the text-to-image tool integrated via MCP:

🚀 安装方式

🎯 零安装配置 (推荐)

方式1: NPX自动下载 (需要NPM发布)

npm install -g @lupinlin1/imagegen-mcp

方式2: GitHub远程执行 (立即可用)

# 一行命令安装脚本
curl -fsSL https://raw.githubusercontent.com/LupinLin1/imagegen-mcp/main/scripts/install.sh | bash

方式3: 本地脚本 (开发者友好)

git clone https://github.com/LupinLin1/imagegen-mcp.git
cd imagegen-mcp
npm install && npm run build

📊 方案对比

方式	安装步骤	网络依赖	启动速度	适用场景
NPX自动下载	0步	首次需要	快	生产环境
GitHub远程	0步	每次需要	中等	快速试用
本地脚本	1步克隆	无	最快	开发测试

📁 更多配置: 查看 examples/mcp-configs/ 获取所有配置示例

Prerequisites

Node.js (v18 or later recommended)
npm or yarn
An OpenAI API key

🎯 零安装配置 (推荐)

**无需任何预安装步骤！**直接配置即可使用：

Cursor 编辑器

{
  "mcpServers": {
    "imagegen-mcp": {
      "command": "npx",
      "args": ["@lupinlin1/imagegen-mcp", "--models", "dall-e-3"],
      "env": {
        "OPENAI_API_KEY": "your_openai_api_key_here"
      }
    }
  }
}

Claude Desktop

{
  "mcpServers": {
    "imagegen-mcp": {
      "command": "npx",
      "args": ["@lupinlin1/imagegen-mcp"],
      "env": {
        "OPENAI_API_KEY": "your_openai_api_key_here"
      }
    }
  }
}

💡 零安装原理

✅ 首次运行: npx 自动下载并缓存包
✅ 后续启动: 使用缓存，启动快速
✅ 自动更新: 始终使用最新版本
✅ 无污染: 不会全局安装任何包

📁 更多配置示例: 查看 examples/mcp-configs/ 目录

Setup

Clone the repository:

git clone <your-repository-url>
cd <repository-directory>

Install dependencies:
```
npm install
# or
yarn install
```
Configure Environment Variables: Create a .env file in the project root by copying the example:
```
cp .env.example .env
```
Edit the .env file and add your OpenAI API key:
```
OPENAI_API_KEY=your_openai_api_key_here
```

Building

To build the TypeScript code into JavaScript:

npm run build
# or
yarn build

This will compile the code into the dist directory.

Running the Server

This section provides details on running the server locally after cloning and setup. For a quick start without cloning, see the Quick Run with npx section.

Using ts-node (for development):

npx ts-node src/index.ts [options]

Using the compiled code:

node dist/index.js [options]

Options:

--models <model1> <model2> ...: Specify which OpenAI models the server should allow. If not provided, it defaults to allowing all models defined in src/libs/openaiImageClient.ts (currently gpt-image-1, dall-e-2, dall-e-3).
- Example using npx (also works for local runs): ... --models gpt-image-1 dall-e-3
- Example after cloning: node dist/index.js --models dall-e-3 dall-e-2

The server will start and listen for MCP requests via standard input/output (using StdioServerTransport).

MCP Tools

The server exposes the following MCP tools:

`text-to-image`

Generates an image based on a text prompt.

Parameters:

text (string, required): The prompt to generate an image from.
model (enum, optional): The model to use (e.g., gpt-image-1, dall-e-2, dall-e-3). Defaults to the first allowed model.
size (enum, optional): Size of the generated image (e.g., 1024x1024, 1792x1024). Defaults to 1024x1024. Check OpenAI documentation for model-specific size support.
style (enum, optional): Style of the image (vivid or natural). Only applicable to dall-e-3. Defaults to vivid.
output_format (enum, optional): Format (png, jpeg, webp). Defaults to png.
output_compression (number, optional): Compression level (0-100). Defaults to 100.
moderation (enum, optional): Moderation level (low, auto). Defaults to low.
background (enum, optional): Background (transparent, opaque, auto). Defaults to auto. transparent requires output_format to be png or webp.
quality (enum, optional): Quality (standard, hd, auto, ...). Defaults to auto. hd only applicable to dall-e-3.
n (number, optional): Number of images to generate. Defaults to 1. Note: dall-e-3 only supports n=1.

Returns:

content: An array containing:
- A text object containing the path to the saved temporary image file (e.g., /tmp/uuid.png).

`image-to-image`

Edits an existing image based on a text prompt and optional mask.

Parameters:

images (string, required): An array of file paths to local images.
prompt (string, required): A text description of the desired edits.
mask (string, optional): A file path of mask image (PNG). Transparent areas indicate where the image should be edited.
model (enum, optional): The model to use. Only gpt-image-1 and dall-e-2 are supported for editing. Defaults to the first allowed model.
size (enum, optional): Size of the generated image (e.g., 1024x1024). Defaults to 1024x1024. dall-e-2 only supports 256x256, 512x512, 1024x1024.
output_format (enum, optional): Format (png, jpeg, webp). Defaults to png.
output_compression (number, optional): Compression level (0-100). Defaults to 100.
quality (enum, optional): Quality (standard, hd, auto, ...). Defaults to auto.
n (number, optional): Number of images to generate. Defaults to 1.

Returns:

content: An array containing:
- A text object containing the path to the saved temporary image file (e.g., /tmp/uuid.png).

Development

Linting: npm run lint or yarn lint
Formatting: npm run format or yarn format (if configured in package.json)

Contributing

Pull Requests (PRs) are welcome! Please feel free to submit improvements or bug fixes.

MCP OpenAI Image Generation Server

🚀 零安装配置！ 直接在MCP客户端中使用，无需任何预安装步骤

{
  "mcpServers": {
    "imagegen-mcp": {
      "command": "npx",
      "args": ["@lupinlin1/imagegen-mcp", "--models", "dall-e-3"],
      "env": { "OPENAI_API_KEY": "your_api_key" }
    }
  }
}

This project provides a server implementation based on the Model Context Protocol (MCP) that acts as a wrapper around OpenAI's Image Generation and Editing APIs (see OpenAI documentation).

Features

Exposes OpenAI image generation capabilities through MCP tools.
Supports text-to-image generation using models like DALL-E 2, DALL-E 3, and gpt-image-1 (if available/enabled).
Supports image-to-image editing using DALL-E 2 and gpt-image-1 (if available/enabled).
Configurable via environment variables and command-line arguments.
Handles various parameters like size, quality, style, format, etc.
Saves generated/edited images to temporary files and returns the path along with the base64 data.

Here's an example of generating an image directly in Cursor using the text-to-image tool integrated via MCP:

🚀 安装方式

🎯 零安装配置 (推荐)

方式1: NPX自动下载 (需要NPM发布)

npm install -g @lupinlin1/imagegen-mcp

方式2: GitHub远程执行 (立即可用)

# 一行命令安装脚本
curl -fsSL https://raw.githubusercontent.com/LupinLin1/imagegen-mcp/main/scripts/install.sh | bash

方式3: 本地脚本 (开发者友好)

git clone https://github.com/LupinLin1/imagegen-mcp.git
cd imagegen-mcp
npm install && npm run build

📊 方案对比

方式	安装步骤	网络依赖	启动速度	适用场景
NPX自动下载	0步	首次需要	快	生产环境
GitHub远程	0步	每次需要	中等	快速试用
本地脚本	1步克隆	无	最快	开发测试

📁 更多配置: 查看 examples/mcp-configs/ 获取所有配置示例

Prerequisites

Node.js (v18 or later recommended)
npm or yarn
An OpenAI API key

🎯 零安装配置 (推荐)

**无需任何预安装步骤！**直接配置即可使用：

Cursor 编辑器

{
  "mcpServers": {
    "imagegen-mcp": {
      "command": "npx",
      "args": ["@lupinlin1/imagegen-mcp", "--models", "dall-e-3"],
      "env": {
        "OPENAI_API_KEY": "your_openai_api_key_here"
      }
    }
  }
}

Claude Desktop

{
  "mcpServers": {
    "imagegen-mcp": {
      "command": "npx",
      "args": ["@lupinlin1/imagegen-mcp"],
      "env": {
        "OPENAI_API_KEY": "your_openai_api_key_here"
      }
    }
  }
}

💡 零安装原理

✅ 首次运行: npx 自动下载并缓存包
✅ 后续启动: 使用缓存，启动快速
✅ 自动更新: 始终使用最新版本
✅ 无污染: 不会全局安装任何包

📁 更多配置示例: 查看 examples/mcp-configs/ 目录

Setup

Clone the repository:

git clone <your-repository-url>
cd <repository-directory>

Install dependencies:
```
npm install
# or
yarn install
```
Configure Environment Variables: Create a .env file in the project root by copying the example:
```
cp .env.example .env
```
Edit the .env file and add your OpenAI API key:
```
OPENAI_API_KEY=your_openai_api_key_here
```

Building

To build the TypeScript code into JavaScript:

npm run build
# or
yarn build

This will compile the code into the dist directory.

Running the Server

This section provides details on running the server locally after cloning and setup. For a quick start without cloning, see the Quick Run with npx section.

Using ts-node (for development):

npx ts-node src/index.ts [options]

Using the compiled code:

node dist/index.js [options]

Options:

--models <model1> <model2> ...: Specify which OpenAI models the server should allow. If not provided, it defaults to allowing all models defined in src/libs/openaiImageClient.ts (currently gpt-image-1, dall-e-2, dall-e-3).
- Example using npx (also works for local runs): ... --models gpt-image-1 dall-e-3
- Example after cloning: node dist/index.js --models dall-e-3 dall-e-2

The server will start and listen for MCP requests via standard input/output (using StdioServerTransport).

MCP Tools

The server exposes the following MCP tools:

`text-to-image`

Generates an image based on a text prompt.

Parameters:

text (string, required): The prompt to generate an image from.
model (enum, optional): The model to use (e.g., gpt-image-1, dall-e-2, dall-e-3). Defaults to the first allowed model.
size (enum, optional): Size of the generated image (e.g., 1024x1024, 1792x1024). Defaults to 1024x1024. Check OpenAI documentation for model-specific size support.
style (enum, optional): Style of the image (vivid or natural). Only applicable to dall-e-3. Defaults to vivid.
output_format (enum, optional): Format (png, jpeg, webp). Defaults to png.
output_compression (number, optional): Compression level (0-100). Defaults to 100.
moderation (enum, optional): Moderation level (low, auto). Defaults to low.
background (enum, optional): Background (transparent, opaque, auto). Defaults to auto. transparent requires output_format to be png or webp.
quality (enum, optional): Quality (standard, hd, auto, ...). Defaults to auto. hd only applicable to dall-e-3.
n (number, optional): Number of images to generate. Defaults to 1. Note: dall-e-3 only supports n=1.

Returns:

content: An array containing:
- A text object containing the path to the saved temporary image file (e.g., /tmp/uuid.png).

`image-to-image`

Edits an existing image based on a text prompt and optional mask.

Parameters:

images (string, required): An array of file paths to local images.
prompt (string, required): A text description of the desired edits.
mask (string, optional): A file path of mask image (PNG). Transparent areas indicate where the image should be edited.
model (enum, optional): The model to use. Only gpt-image-1 and dall-e-2 are supported for editing. Defaults to the first allowed model.
size (enum, optional): Size of the generated image (e.g., 1024x1024). Defaults to 1024x1024. dall-e-2 only supports 256x256, 512x512, 1024x1024.
output_format (enum, optional): Format (png, jpeg, webp). Defaults to png.
output_compression (number, optional): Compression level (0-100). Defaults to 100.
quality (enum, optional): Quality (standard, hd, auto, ...). Defaults to auto.
n (number, optional): Number of images to generate. Defaults to 1.

Returns:

content: An array containing:
- A text object containing the path to the saved temporary image file (e.g., /tmp/uuid.png).

Development

Linting: npm run lint or yarn lint
Formatting: npm run format or yarn format (if configured in package.json)

Contributing

Pull Requests (PRs) are welcome! Please feel free to submit improvements or bug fixes.