npm package: @singularity2045/image-generator-mcp-server
Description: An MCP server that generates images using GPT Image (gpt-image-1.5) based on text prompts
Author: Al
Latest version: 0.2.2

# GPT Image Generator MCP Server

<div align="center">

<img src="./logo.webp" alt="GPT Image Generator Logo" width="200"/>

**Generate beautiful AI images using GPT Image (gpt-image-1.5) in any MCP-compatible application**

[![TypeScript](https://img.shields.io/badge/TypeScript-5.9-blue.svg)](https://www.typescriptlang.org/)
[![OpenAI](https://img.shields.io/badge/OpenAI-GPT%20Image%201.5-green.svg)](https://openai.com/)
[![MCP](https://img.shields.io/badge/MCP-Model%20Context%20Protocol-purple.svg)](https://spec.modelcontextprotocol.io/specification/2024-11-05/)

</div>

## 🌟 Overview

This is a Model Context Protocol (MCP) server that brings OpenAI's GPT Image (gpt-image-1.5) generation capabilities to any MCP-compatible application including Cursor, Claude Desktop, Windsurf, and more. With a simple function call, you can generate high-quality AI images and save them to any location on your filesystem.

> **💡 Fun fact**: The logo for this project was generated using this very tool!

<div align="center">
<i>Generate your own amazing images with just a few lines of code!</i>
</div>

## ✨ Features

- **Powerful Image Generation**: Uses OpenAI's state-of-the-art GPT Image model (`gpt-image-1.5`)
- **Image Editing**: Edit existing images with text prompts—style transfer, object removal, compositing, and more
- **AI Upscaling (Optional)**: Upscale images to high resolution using [Topaz Labs Enhance API](https://www.topazlabs.com/api)
- **Built-in Prompting Guide**: Includes a comprehensive prompting guide resource with best practices
- **Prompting Guide Guardrail**: Ensures AI models read the prompting guide before generating images
- **Direct Cursor Integration**: Works seamlessly within your editor
- **Flexible Output Paths**: Save images anywhere on your filesystem
- **Automatic Directory Creation**: Directories are created if they don't exist
- **Smart File Extension Handling**: `.png` extension is added automatically

## 🔄 Cross-Platform Compatibility

Since this is an MCP (Model Context Protocol) server, it's compatible with **any application that supports the MCP protocol**, not just Cursor!

### Compatible Applications

- **[Cursor](https://www.cursor.com/)**: AI-powered code editor built on VS Code that features code generation, multi-file editing, codebase understanding, and chat interface
- **[Claude Desktop](https://claude.ai/download)**: Anthropic's standalone Claude application
- **[Windsurf](https://codeium.com/windsurf)**: AI-powered integrated development environment (IDE) by Codeium
- **[Cline](https://cline.bot)**: AI-powered coding assistant that integrates with IDEs as an autonomous agent
- **Any other MCP-compatible application**

Simply follow the installation instructions for your specific platform, and the image generation capabilities will be available in any MCP-supporting tool you use!

## 📋 Requirements

- Node.js 18 or higher
- An OpenAI API key with Image API access
- (Optional) A Topaz Labs API key for high-resolution upscaling

## 🚀 Quick Start

### Installation

#### Option 1: Install from npm (Recommended)

```bash
# Install globally
npm install -g @singularity2045/image-generator-mcp-server

# Verify installation
image-generator --version
```

#### Option 2: Install from Source

```bash
# Clone the repository
git clone https://github.com/angelol/image-generator-mcp-server.git
cd image-generator-mcp-server

# Install dependencies
npm install

# Build the project
npm run build

# Link globally
npm link
```

### Configuration

Create a `.env` file in the project root:

```
OPENAI_API_KEY=your_openai_api_key_here
TOPAZ_API_KEY=your_topaz_api_key_here  # Optional: enables high-resolution upscaling
```

| Variable | Required | Description |
|----------|----------|-------------|
| `OPENAI_API_KEY` | Yes | Your OpenAI API key for image generation |
| `TOPAZ_API_KEY` | No | Your [Topaz Labs API key](https://www.topazlabs.com/api) for AI upscaling (enables `upscale_image` tool and upscale options in `generate_image`) |

### Platform-Specific Setup

#### Cursor

Add the server configuration to Cursor's config file:

**MacOS/Linux**: `~/.cursor/mcp.json`  
**Windows**: `%USERPROFILE%\.cursor\mcp.json`

```json
{
  "mcpServers": {
    "image-generator": {
      "command": "image-generator",
      "env": {
        "OPENAI_API_KEY": "your_openai_api_key_here",
        "TOPAZ_API_KEY": "your_topaz_api_key_here"
      }
    }
  }
}
```

> **Note**: The `TOPAZ_API_KEY` is optional. If not provided, image generation will still work, but upscaling features will be disabled.

After configuration, restart Cursor for the tool to be available.

#### Claude Desktop

Add the server configuration to Claude Desktop's config file:

**MacOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
**Windows**: `%APPDATA%/Claude/claude_desktop_config.json`

```json
{
  "mcpServers": {
    "image-generator": {
      "command": "image-generator",
      "env": {
        "OPENAI_API_KEY": "your_openai_api_key_here",
        "TOPAZ_API_KEY": "your_topaz_api_key_here"
      }
    }
  }
}
```

> **Note**: The `TOPAZ_API_KEY` is optional. If not provided, image generation will still work, but upscaling features will be disabled.

After configuration, restart Claude Desktop for the tool to be available.

#### Other MCP Applications

Most MCP-compatible applications have a similar configuration process:

1. Install and link the package globally as mentioned above
2. Configure the application to recognize the `image-generator` command
3. Set the OPENAI_API_KEY environment variable
4. Restart the application

Consult your specific application's documentation for detailed MCP server integration steps.

### Using with Cursor Agent

Restart Cursor after installation, then it can be used by the Cursor Agent.

Cursor's AI assistant can be instructed to generate images for your projects through natural language prompts. This is especially powerful when building websites, creating assets, or designing UI elements.

#### Example Workflow

1. **Ask the agent to generate an image for your project**:

   ```
   Create a hero image for my travel website featuring a tropical beach sunset
   ```

2. **The agent will use the tool with appropriate parameters**:

   ```javascript
   mcp_image_generator_generate_image({
     prompt: "A stunning tropical beach at sunset with golden light reflecting on gentle waves, palm trees silhouetted against an orange and purple sky, perfect for a travel website hero image",
     outputPath: "/Users/yourusername/myproject/public/images/hero-sunset"
   })
   ```

3. **Use the generated image in your code**:
   
   The agent can help you incorporate the image into your project:

   ```html
   <div class="hero">
     <img src="/images/hero-sunset.png" alt="Tropical beach sunset" />
     <h1>Discover Paradise</h1>
   </div>
   ```

#### Tips for Effective Image Generation with the Agent

- **Be specific about style**: Mention "photorealistic," "cartoon," "minimalist," etc.
- **Describe the intended use**: "for a logo," "for a button," "for a background"
- **Specify dimensions in your prompt**: "create a wide banner image," "create a square profile picture"
- **Request variations**: Ask the agent to generate multiple versions with slight prompt modifications
- **Include art direction**: "in the style of Monet," "with vibrant colors," "with a dark, moody atmosphere"

#### Common Use Cases

- **Website Assets**: "Generate icons for my navigation menu with a consistent blue theme"
- **UI Components**: "Create button backgrounds with a subtle gradient"
- **Blog Images**: "Generate a featured image for my article about machine learning"
- **App Mockups**: "Create screen mockups for my fitness tracking app"
- **Placeholder Content**: "Generate placeholder product images for my e-commerce site"
- **Marketing Materials**: "Create social media banner images for my product launch"

During development, you can quickly iterate by asking the Cursor agent to modify existing images: "Generate a lighter version of the previous logo" or "Create the same image but in a different style."

## 📘 Documentation

### Prompting Guide Resource

The server provides a built-in prompting guide resource at `image-generator://prompting-guide` containing best practices for crafting effective prompts with GPT Image 1.5. This resource covers:

- Prompt structure and composition
- Specificity and quality cues
- Text rendering in images
- Size selection guidelines
- Use cases for generation and editing
- Character consistency workflows

#### Prompting Guide Guardrail

To ensure high-quality results, the server enforces that AI models read the prompting guide before using `generate_image` or `edit_image`. If a model attempts to generate or edit an image without first reading the guide:

1. The tool returns an error with `isError: true`
2. The full prompting guide content is included in the error message
3. The model can then retry after reviewing the guide

This guardrail helps ensure that AI models follow best practices for prompting, resulting in better image outputs.

### Tool Reference

#### Function Naming

The function name will vary depending on how you've configured the MCP server in each application. The examples in this documentation use `mcp_image_generator_generate_image`, but your specific configuration might result in a different function name.

#### `generate_image`

Generates an image based on a text prompt. Optionally upscales the result using Topaz Labs AI (requires `TOPAZ_API_KEY`).

**Parameters:**

| Parameter | Type | Description | Required |
|-----------|------|-------------|----------|
| `prompt` | string | Text description of the image to generate | Yes |
| `outputPath` | string | Absolute path where to save the image | Yes |
| `size` | `"auto" \| "1024x1024" \| "1536x1024" \| "1024x1536"` | Output image size for GPT Image. Defaults to `1024x1024`. | No |
| `upscaleWidth` | number | Target width for upscaling (1-32000 pixels). Requires `upscaleHeight`. | No |
| `upscaleHeight` | number | Target height for upscaling (1-32000 pixels). Requires `upscaleWidth`. | No |
| `upscaleModel` | `"Standard V2" \| "Low Resolution V2" \| "High Fidelity V2" \| "CGI"` | AI model for upscaling. Defaults to `High Fidelity V2`. | No |

> **Note**: The upscale parameters are only available when `TOPAZ_API_KEY` is configured.

**Returns:**

A success message with the saved file path and generation details.

**Example (basic):**

```javascript
mcp_image_generator_generate_image({
  prompt: "A futuristic city with flying cars and neon lights",
  outputPath: "/Users/yourusername/Pictures/generated_images/future_city",
  size: "1536x1024"
})
```

**Example (with upscaling):**

```javascript
mcp_image_generator_generate_image({
  prompt: "A detailed portrait of a robot",
  outputPath: "/Users/yourusername/Pictures/robot_portrait",
  size: "1024x1024",
  upscaleWidth: 4096,
  upscaleHeight: 4096,
  upscaleModel: "High Fidelity V2"
})
```

---

#### `edit_image`

Edits one or more images using a text prompt. Supports style transfer, object removal, compositing, background removal, and more. Optionally upscales the result using Topaz Labs AI (requires `TOPAZ_API_KEY`).

**Parameters:**

| Parameter | Type | Description | Required |
|-----------|------|-------------|----------|
| `inputImages` | string[] | Array of absolute paths to input images. First image is the base; additional images are references for compositing or style transfer. | Yes |
| `prompt` | string | Description of the edit to perform | Yes |
| `outputPath` | string | Absolute path where to save the edited image | Yes |
| `size` | `"auto" \| "1024x1024" \| "1536x1024" \| "1024x1536"` | Output image size. Defaults to `auto`. | No |
| `background` | `"transparent" \| "opaque" \| "auto"` | Background type. Use `transparent` for product extraction. Defaults to `auto`. | No |
| `upscaleWidth` | number | Target width for upscaling (1-32000 pixels). Requires `upscaleHeight`. | No |
| `upscaleHeight` | number | Target height for upscaling (1-32000 pixels). Requires `upscaleWidth`. | No |
| `upscaleModel` | `"Standard V2" \| "Low Resolution V2" \| "High Fidelity V2" \| "CGI"` | AI model for upscaling. Defaults to `High Fidelity V2`. | No |

> **Note**: The upscale parameters are only available when `TOPAZ_API_KEY` is configured.

**Returns:**

A success message with the saved file path and edit details.

**Example (style transfer):**

```javascript
mcp_image_generator_edit_image({
  inputImages: ["/Users/yourusername/Pictures/photo.png", "/Users/yourusername/Pictures/style_reference.png"],
  prompt: "Apply the artistic style from image 2 to image 1",
  outputPath: "/Users/yourusername/Pictures/styled_photo"
})
```

**Example (background removal):**

```javascript
mcp_image_generator_edit_image({
  inputImages: ["/Users/yourusername/Pictures/product.png"],
  prompt: "Remove the background, keep only the product",
  outputPath: "/Users/yourusername/Pictures/product_transparent",
  background: "transparent"
})
```

---

#### `upscale_image`

Upscales an existing image to higher resolution using Topaz Labs AI. Only available when `TOPAZ_API_KEY` is configured.

**Parameters:**

| Parameter | Type | Description | Required |
|-----------|------|-------------|----------|
| `inputPath` | string | Absolute path to the image to upscale (PNG or JPEG) | Yes |
| `outputPath` | string | Absolute path where to save the upscaled image | Yes |
| `width` | number | Target width in pixels (1-32000) | Yes |
| `height` | number | Target height in pixels (1-32000) | Yes |
| `model` | `"Standard V2" \| "Low Resolution V2" \| "High Fidelity V2" \| "CGI"` | AI model to use. Defaults to `High Fidelity V2`. | No |

**Available Models:**

| Model | Best For |
|-------|----------|
| `Standard V2` | General-purpose upscaling, balances detail and speed |
| `Low Resolution V2` | Low-resolution images, web graphics, screenshots |
| `High Fidelity V2` | High-quality images, professional photography |
| `CGI` | CGI and digital illustrations, computer-generated images |

**Returns:**

A success message with the saved file path and upscale details.

**Example:**

```javascript
mcp_image_generator_upscale_image({
  inputPath: "/Users/yourusername/Pictures/photo.png",
  outputPath: "/Users/yourusername/Pictures/photo_4k",
  width: 3840,
  height: 2160,
  model: "High Fidelity V2"
})
```

## 🛠️ Development

### Setup Development Environment

```bash
# Install dependencies
npm install

# Build in watch mode for development
npm run watch
```

### The Development Workflow

After making changes:

1. Build the project: `npm run build`
2. Link the package: `npm link`
3. **Restart Cursor completely**
4. Test your changes

> ⚠️ **Important**: Cursor only establishes connections to MCP servers at startup. Your changes won't take effect until Cursor is restarted, even if the tools appear to be working.

### Project Structure

```
image-generator-mcp-server/
├── src/
│   ├── index.ts           # Main server implementation
│   ├── image-generator.ts # OpenAI Image API interaction
│   ├── topaz-upscaler.ts  # Topaz Labs API integration
│   ├── file-saver.ts      # File system operations
│   └── types.ts           # TypeScript interfaces
├── build/                 # Compiled JavaScript
├── .cursorrules           # Cursor rules for the project
├── package.json           # Project dependencies
└── README.md              # This file
```

## 🐛 Troubleshooting

### Common Issues

- **"Not connected" errors**: Make sure you've restarted Cursor after building/linking.
- **Image generation fails**: Check that your OpenAI API key is valid and has Image API access.
- **Permission errors**: Ensure you have write permissions for the target directory.

### Debugging

You can use the MCP Inspector for debugging:

```bash
npm run inspector
```

> **⚠️ Warning**: The Inspector has a timeout of 10 seconds. Since image generation often takes longer than this, you may see timeout errors. For testing the `generate_image` tool, it's best to test directly in Cursor after rebuilding and restarting.

## 🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add some amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request

## 📜 License

This project is licensed under the MIT License - see the LICENSE file for details.

## 🙏 Acknowledgments

- OpenAI for the Image API
- [Topaz Labs](https://www.topazlabs.com/) for the Enhance API for high-quality AI upscaling
- The Model Context Protocol team for the MCP specification
- Cursor team for the editor integration
- [Sammy Lebbie (sammyl720)](https://github.com/sammyl720/image-generator-mcp-server) for creating the initial version of this project that provided a starting point for our implementation
- [Claude](https://claude.ai), the AI assistant from Anthropic, who helped modernize this codebase and create this documentation

---

<div align="center">
Made with ❤️ for the developer community
</div>