GPT Image Generator MCP Server

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

🌟 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!

✨ 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
• 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: AI-powered code editor built on VS Code that features code generation, multi-file editing, codebase understanding, and chat interface
• Claude Desktop: Anthropic's standalone Claude application
• Windsurf: AI-powered integrated development environment (IDE) by Codeium
• Cline: 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)

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

# Verify installation
image-generator --version

Option 2: Install from Source

# 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 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

{
  "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

{
  "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:

   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:

   <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):

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):

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):

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):

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:

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

# 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:

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 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) for creating the initial version of this project that provided a starting point for our implementation
• Claude, the AI assistant from Anthropic, who helped modernize this codebase and create this documentation