gpt-image MCP

MCP server for AI-powered image generation using OpenAI's gpt-image-1 and gpt-image-2 models with advanced text rendering and native transparency support.

Features

• Advanced text rendering with gpt-image-1 - Crisp, legible typography and logos in generated images
• Native transparency support - Built-in transparent background without post-processing
• Multi-format output (PNG, JPEG, WebP) - Flexible format options with optimized compression
• Flexible dimensions and aspect ratios - Square (1024×1024), landscape (1536×1024), and portrait (1024×1536)
• Batch image editing capabilities - Process multiple images with parallel processing
• Token-optimized MCP responses - Efficient response formats for MCP protocol limits

Installation

Recommended: Using npx

{
  "mcpServers": {
    "gpt-image-mcp": {
      "command": "npx",
      "args": ["@napolab/gpt-image-mcp"],
      "env": {
        "OPENAI_API_KEY": "sk-your-api-key"
      }
    }
  }
}

Alternative: Local Installation

npm install -g @napolab/gpt-image-mcp

Claude Desktop Configuration

Configure in ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "gpt-image-mcp": {
      "command": "npx",
      "args": ["@napolab/gpt-image-mcp"],
      "env": {
        "OPENAI_API_KEY": "sk-your-api-key"
      }
    }
  }
}

Configuration

Environment Variables

Variable	Required	Default	Description
OPENAI_API_KEY	Yes	-	Your OpenAI API key
DEFAULT_OUTPUT_DIR	No	./generated_images	Default output directory
DEFAULT_IMAGE_SIZE	No	1024x1024	Default image dimensions
DEFAULT_IMAGE_QUALITY	No	standard	Default quality (standard/hd)
DEFAULT_OUTPUT_FORMAT	No	png	Default format (png/jpeg/webp)

Available Tools

generate-image

Generate images using gpt-image-1 with advanced text rendering and superior instruction following.

Parameters:

Parameter	Type	Required	Default	Description
prompt	string	Yes	-	Image description (English only)
aspect_ratio	string	No	square	"square", "landscape", or "portrait"
quality	string	No	standard	"standard" or "hd"
output_directory	string	No	./generated_images	Directory to save the image
filename	string	No	-	Custom filename
save_to_file	boolean	No	true	Whether to save locally
include_base64	boolean	No	false	Include base64 in response

Example:

await client.callTool("generate-image", {
  prompt: "A serene Japanese garden with cherry blossoms",
  aspect_ratio: "landscape",
  quality: "hd",
});

edit-image

Edit existing images with AI-powered modifications including inpainting, outpainting, style transfer, and background changes.

Parameters:

Parameter	Type	Required	Default	Description
source_image	object	Yes	-	Image input (URL, base64, or local file)
edit_prompt	string	Yes	-	Description of desired changes (English only)
edit_type	string	Yes	-	Type of edit to perform
strength	number	No	0.8	Edit strength (0.0 to 1.0)
preserve_composition	boolean	No	true	Maintain original composition
output_format	string	No	png	Output format

Edit Types:

• inpaint - Fill in or modify specific areas
• outpaint - Extend image beyond boundaries
• background_change - Replace or modify background
• style_transfer - Apply artistic styles
• object_removal - Remove unwanted objects
• variation - Create variations of original

Example:

await client.callTool("edit-image", {
  source_image: {
    type: "local",
    value: "/path/to/image.jpg",
  },
  edit_prompt: "Add a sunset sky background",
  edit_type: "background_change",
});

batch-edit

Apply the same edit to multiple images efficiently with parallel processing.

Parameters:

Parameter	Type	Required	Default	Description
images	array	Yes	-	Array of image inputs
edit_prompt	string	Yes	-	Edit description (English only)
edit_type	string	Yes	-	Type of edit to apply
batch_settings	object	No	-	Batch processing configuration

Example:

await client.callTool("batch-edit", {
  images: [
    { type: "local", value: "/path/to/image1.jpg" },
    { type: "local", value: "/path/to/image2.jpg" },
  ],
  edit_prompt: "Apply vintage sepia filter",
  edit_type: "style_transfer",
});

Usage Examples

Basic Image Generation

// Generate a simple image
const result = await client.callTool("generate-image", {
  prompt: "A modern minimalist logo design",
  aspect_ratio: "square",
  quality: "hd",
});

console.log("Generated image:", result.data.file_path);

Advanced Options

// Generate with all parameters
const result = await client.callTool("generate-image", {
  prompt: "Professional product photography of a smartphone",
  aspect_ratio: "portrait",
  quality: "hd",
  output_directory: "./product_images",
  filename: "smartphone_hero",
  output_format: "png",
  include_base64: true,
});

Image Editing

// Generate base image
const baseImage = await client.callTool("generate-image", {
  prompt: "A mountain landscape",
  aspect_ratio: "landscape",
});

// Edit the generated image
const editedImage = await client.callTool("edit-image", {
  source_image: {
    type: "local",
    value: baseImage.data.file_path,
  },
  edit_prompt: "Add dramatic storm clouds",
  edit_type: "background_change",
  strength: 0.7,
});

Batch Processing

// Process multiple images
const result = await client.callTool("batch-edit", {
  images: [
    { type: "local", value: "image1.jpg" },
    { type: "local", value: "image2.jpg" },
    { type: "local", value: "image3.jpg" },
  ],
  edit_prompt: "Apply Instagram-style filter",
  edit_type: "style_transfer",
  batch_settings: {
    max_concurrent: 3,
    error_handling: "continue_on_error",
  },
});

Development

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests for new functionality
5. Submit a pull request

Testing

# Run tests
npm test

# Run tests in watch mode
npm run test:watch

# Run linting
npm run lint

# Type checking
npm run typecheck

Building

# Build for production
npm run build

# Development mode with hot reload
npm run dev

License

MIT License - see the LICENSE file for details.

Support

• Documentation - Full documentation and examples
• GitHub Issues
• OpenAI API Documentation
• MCP Protocol Documentation