# MCP OpenAI Image Generation Server
[](https://www.npmjs.com/package/imagegen-mcp)
This project provides a server implementation based on the [Model Context Protocol (MCP)](https://modelcontextprotocol.io/introduction) that acts as a wrapper around OpenAI's Image Generation and Editing APIs (see [OpenAI documentation](https://platform.openai.com/docs/api-reference/images)).
## 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:
## Quick Run with npx
You can run the server directly from npm using `npx` (requires Node.js and npm):
```bash
npx imagegen-mcp [options]
```
See the [Running the Server](#running-the-server) section for more details on options and running locally.
## Prerequisites
* Node.js (v18 or later recommended)
* npm or yarn
* An OpenAI API key
## Integration with Cursor
You can easily integrate this server with Cursor to use its image generation capabilities directly within the editor:
1. **Open Cursor Settings:**
* Go to `File > Preferences > Cursor Settings` (or use the shortcut `Ctrl+,` / `Cmd+,`).
2. **Navigate to MCP Settings:**
* Search for "MCP" in the settings search bar.
* Find the "Model Context Protocol: Custom Servers" setting.
3. **Add Custom Server:**
* Click on "Edit in settings.json".
* Add a new entry to the `mcpServers` array. It should look something like this:
```json
"mcpServers": [
"image-generator-gpt-image": {
"command": "npx imagegen-mcp --models gpt-image-1",
"env": {
"OPENAI_API_KEY": "xxx"
}
}
// ... any other custom servers ...
]
```
* **Customize the command:**
* You can change the `--models` argument in the `command` field to specify which models you want Cursor to have access to (e.g., `--models dall-e-3` or `--models gpt-image-1`). Make sure your OpenAI API key has access to the selected models.
4. **Save Settings:**
* Save the `settings.json` file.
Cursor should now recognize the "OpenAI Image Gen" server, and its tools (`text-to-image`, `image-to-image`) will be available in the MCP tool selection list (e.g., when using `@` mention in chat or code actions).
## Setup
1. **Clone the repository:**
```bash
git clone
cd
```
2. **Install dependencies:**
```bash
npm install
# or
yarn install
```
3. **Configure Environment Variables:**
Create a `.env` file in the project root by copying the example:
```bash
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:
```bash
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](#quick-run-with-npx) section.
**Using ts-node (for development):**
```bash
npx ts-node src/index.ts [options]
```
**Using the compiled code:**
```bash
node dist/index.js [options]
```
**Options:**
* `--models ...`: 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.