gpt-image-1-mcp by naporin0624 - MCP Server

gpt-image-1 MCP

MCP server for AI-powered image generation using OpenAI's gpt-image-1 model 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-1-mcp": {
      "command": "npx",
      "args": ["@napolab/gpt-image-1-mcp"],
      "env": {
        "OPENAI_API_KEY": "sk-your-api-key"
      }
    }
  }
}

Alternative: Local Installation

npm install -g @napolab/gpt-image-1-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-1-mcp": {
      "command": "npx",
      "args": ["@napolab/gpt-image-1-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

Fork the repository
Create a feature branch
Make your changes
Add tests for new functionality
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 file for details.

Support

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