# OpenAI Image Generation MCP Server

A [Model Context Protocol](https://github.com/modelcontextprotocol/python-sdk) (MCP) Server that interfaces with the [OpenAI API](https://platform.openai.com/) for image generation using the `gpt-image-1` model.

## Features

- Generate images using OpenAI's gpt-image-1 model with various customization options
- Edit images by providing source images and prompts
- Save generated images to local storage in specified folders
- Control image formats, quality, and background transparency

## Installation

Install [uv](https://docs.astral.sh/uv/getting-started/installation/)

On Mac you can install it using [homebrew](https://brew.sh/)

```shell
brew install uv
```

## Usage with Claude Code

Configure Claude Code to use this MCP server by updating your `.cursor/mcp.json` or other agent configuration:

```json
{
  "mcpServers": {
    "openai-image": {
      "command": "uv",
      "args": [
        "--directory",
        "/Users/marabian/mcp-servers/openai-imagegen-mcp",
        "run",
        "mcp",
        "run",
        "main.py"
      ],
      "env": {
        "OPENAI_API_KEY": "your_api_key_here",
        "DEFAULT_SAVE_DIR": "/path/to/default/save/directory"
      }
    }
  }
}
```

### Important Configuration Notes:

1. Replace `your_api_key_here` with your actual OpenAI API key.

2. For the `DEFAULT_SAVE_DIR`:

   - Set this to a directory where you want to save all generated images
   - You can use a relative path like `./images` within your project
   - For projects, consider using a path like `${PROJECT_ROOT}/generated-images`
   - Defaults to `./images` in the MCP server directory if not specified

3. When working in different projects:
   - The agent will save images to `DEFAULT_SAVE_DIR` by default
   - You can override this within each tool call using the `save_dir` parameter
   - Images will be organized with unique timestamps to prevent conflicts

## Available Tools

The OpenAI Image Generation MCP Server provides the following tools:

### Image Generation

- `generate_image` - Generate an image based on a text prompt
- `edit_image` - Edit an existing image based on a new prompt
- `get_available_models` - List available OpenAI image generation models

### Image Management

- `list_saved_images` - List images saved in the specified directory
- `set_save_directory` - Set the directory where generated images will be saved

## Examples

### Generating an Image

```python
# Generate a landscape image with transparent background
generate_image(
    prompt="A serene mountain landscape at sunset",
    size="1536x1024",
    background="transparent",
    output_format="png",
    save_dir="/path/to/project/images",
    filename="sunset_landscape"
)
```

### Editing Images

```python
# Combine multiple source images into a new composition
edit_image(
    prompt="Create a cohesive scene with these objects",
    image_paths=["/path/to/image1.png", "/path/to/image2.png"],
    quality="high",
    save_dir="/path/to/project/edits",
    filename="composed_scene"
)
```